Legacy Codebase: A Love Story

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<int, string>” 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/