After some years, working with a > 10 years old legacy PHP codebase, I can truly say: you can escape the legacy codebase and introduce whatever is helpful, in a well-maintained system.
Here are 5 important steps that I have done:
- Custom error handling: Reporting notices for developers, report bad “assert” calls in the dev container, report bad indexes, reporting wrong code usage, …
- Autocompletion for everything: classes, properties, SQL queries, CSS, HTML, JavaScript in PHP (e.g. via /* @lang JavaScript */ in PhpStorm), …
- Static-Code Analysis: Preventing bugs is even better than fixing bugs, so just stop stupid bugs and use types in your code.
- Automate the refactoring: With tools like PHP-CS-Fixer or Rector you can not only fix your code one time, you can fix any future wrong usage of the code.
- Do not use strings for code: Just use constants, classes, properties, … use something that can be processes by your static-code analysis and something where you will have autocompletion.
Here are 5 additional steps that I already introduce:
- Sentry: External error collecting (aggregating) tool + custom handler to see e.g. IDs of every Active Record object.
- Generics: via PHPDocs + autocompletion via PhpStorm
- No “mixed” types: Now we use something like, e.g. “array” instead of “array”.
- PSR standards: e.g. PSR-15 request handler, PSR-11 container, PSR-3 logger, …
- Code Style: One code style to rule them all, we use PHP-CS-Fixer and PHP-Code-Sniffer to check / fix our code style for all ~ 10,000 PHP classes.
Here is what helped me mostly while working with old existing code.
First rule, first:
think or / and ask someone in the team
Analyzing: Here are some things that helped my analyzing software problems in our codebase.
- Errors: Better error handling / reporting with a custom error handler, with all relevant information.
- Understandable logging: Hint, you can just use syslog for medium-sized applications.
- Grouping errors: Displaying and grouping all the stuff (PHP / JS / errors + our own custom reports) into Sentry (https://sentry.io/), now you can easily see how e.g. how many customers are effected from an error.
- git history: Often new bugs were introduced with the latest changes (at least in often used components), so that good commit messages are really helpful to find this changes. (https://github.com/voku/dotfiles/wiki/git-commit-messages)
- Local containers: If you can just download the application with a database dump from yesterday, you can analyze many problems without touching any external server.
- Linux tools: mytop, strace, htop, iotop, lsof, …
- Database tools: EXPLAIN [SQL], IDE integration / autocompletion, …
Fixing: Here are some tricks for fixing existing code more easily.
- IDE: PhpStorm with auto-completion and suggestions (including results from static analysis)
- auto-code-style formatter: (as pre-commit hook) is also helpful because I do not need to think about this anymore while fixing code
- git stuff: sometimes it can also be helpful to understand git and how to revert or cherry-pick some changes
Preventing: Here are some hints how you can prevent some bugs.
- custom static analysis rules: http://suckup.de/2022/07/php-code-quality-with-custom-tooling-extensions/
- root cause: fixing the root cause of a problem, sometimes this is very hard because you need to fully understand the problem first, bust mostly spending this time is a good investment
- testing: writing a test is always a good idea, at least to prevent the same problem
Job: If you now would like to work with this codebase (PHP 8 | MySQL 8 | Ubuntu), please contact me and take a look at this job offer: https://meerx.de/karriere/softwareentwickler-softwareentwicklerin/
