black and gray laptop computer turned on doing computer codes

Legacy Codebase: A Love Story

This blog post has been published on 2023-01-04 and may be out of date.

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 (, 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. (
  • 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:
  • 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:

Published by


Lars Moelleken | Ich bin root, ich darf das!

%d bloggers like this: