In my daily work I regularly take over legacy projects from customers that have a relatively old code base and shall be upgraded in order to be compatible with latest software versions, PHP versions and so on. Within those projects I always use several techniques to quickly get to work but at the same time carefully try to not introduce new defects.
In the following blog post I will take you through several tips when you take over legacy projects.
1. Add version history
The first advise sounds very obvious, but it is not even in 2021 for every legacy project: use a version control like
So one of the very first steps is to go through all code files. Then you should filter out
- sensitive data
- extremely large files, like images, CSV files, etc.
- old backup files
- cache directories and temporary files
Then add everything else to the repository.
This way it is very easy in the future to compare all changes with the base version when you have taken over the project initially.
While going through all files and customizations individually you should also look for obvious security issues and create tasks for fixing them later. A very handy and quick helper to find PHP syntax errors is e.g.
find . -type f -name '*.php' -print0 | xargs -0 -n1 -P4 php -l -n | (! grep -v "No syntax errors detected" )
In addition also the
phpcs code sniffer together with the PHPCompatibility standard is a very good way to find common syntax errors or flaws in the source code base.
2. Setup development environment
The next step is to create Docker containers and get the application up and running within those containers in your local development environment.
For me personally the Docker containers from
webdevops/php-apache-dev have proven a very stable and fast environment where everything from Xdebug to Ioncube is already pre-installed.
For the local development environment it is also very important to work with anonymized customer data. This means that after you have created a dump of the production database you have to go through every database table and check if there is personal customer data that needs to be anonymized. Depending on your software solution there may also be automated tools for that like
n98-magerun for Magento, that can help you with the anonymization.
3. Observe everything
Getting a better understanding of the inner workings of the application is the next important step. This can and should be done in multiple ways:
Debug locally with Xdebug to get an understanding of the application. This is especially useful if you are not so familiar with the application or software that you are taking over.
Additionally implement a basic logging class and log to
stdout or a separate log file. For a more advanced solution you could also setup an ELK logging solution.
Then add log calls to every relevant class and action. I would always recommend to use either the internal logger of the application (e.g.
Mage::log() in case of Magento 1 or OpenMage) or the PHP monolog package for that.
The logging is especially useful as there are high chances that if the application has not been updated for quite a while that you will discover bugs and issues from these logs. The sooner you find those bugs, the less time it will cost them.
4. Write (end-to-end) tests
Of course this point is very discussable as you often have the problem that legacy applications are not prepared for testing. In addition most customers are not willing to pay for these tests, but there should be ways to package that within your quote. Nevertheless from my experience I would at least recommend to try to test the most critical application paths and processes. At least end-to-end tests should be doable for every project.
For Magento 1 there is the great Ecomdev_Phpunit extension that simplifies writing unit tests. All my Magento extensions are equipped with unit tests to ensure best quality standards. You can find more information in the FAQ on how to run the unit tests for Magento extensions
These are my main points when taking over legacy projects from my clients. How do you handle these?