README

Legacy code is code without tests. Over the years I have helped many a team introduce (unit) testing into a legacy code base, making it "less legacy" step by step.

The de-legacy-fy command-line tool is an attempt to put concepts and ideas that proved to be effective at dealing with legacy PHP applications into code and make them as reusable as possible.

Installation

PHP Archive (PHAR)

The easiest way to obtain de-legacy-fy is to download a PHP Archive (PHAR) that has all required dependencies of de-legacy-fy bundled in a single file:

$ wget https://phar.phpunit.de/de-legacy-fy.phar
$ chmod +x de-legacy-fy.phar
$ mv de-legacy-fy.phar /usr/local/bin/de-legacy-fy

You can also immediately use the PHAR after you have downloaded it, of course:

$ wget https://phar.phpunit.de/de-legacy-fy.phar
$ php de-legacy-fy.phar

Composer

You can add this tool as a local, per-project, development-time dependency to your project using Composer:

$ composer require --dev sebastian/de-legacy-fy

You can then invoke it using the vendor/bin/de-legacy-fy executable.

Usage Examples

Generating characterization tests using execution trace data

Characterization Tests are an attempt to lock existing behavior into an untested or undocumented system. They are described briefly in Michael Feathers' book "Working Effectively With Legacy Code", among other places.

We can automatically generate a data provider for a PHPUnit-based characterization test using execution trace data that we can collect with Xdebug.

Consider the following rather contrived and simple example:

<?php
function add($a, $b)
{
    return $a + $b;
}

add(1, 2);

The command below executes the PHP script shown above with Xdebug's execution tracing enabled and configured to emit machine-readable output that includes arguments and return values:

$ php -d xdebug.auto_trace=1 -d xdebug.trace_format=1 -d xdebug.collect_params=5 -d xdebug.collect_return=1 test.php

You can see the execution trace data collected by Xdebug below:

$ cat /tmp/trace.4251619279.xt
Version: 2.5.3
File format: 4
TRACE START [2014-06-27 10:40:40]
1	0	0	0.000282	279896	{main}	1		/home/sb/test.php	0	0
2	1	0	0.000371	280136	add	1		/home/sb/test.php	7	2	aToxOw==	aToyOw==
2	1	1	0.000440	280256
2	1	R			aTozOw==
1	0	1	0.000470	280016
1	0	R			aToxOw==
            0.000648	8488
TRACE END   [2014-06-27 10:40:40]

The generate-characterization-test command of de-legacy-fy can automatically generate a data provider method for use with PHPUnit:

$ de-legacy-fy generate-characterization-test add /tmp/trace.4251619279.xt CharacterizationTest CharacterizationTest.php
de-legacy-fy 2.0.0 by Sebastian Bergmann.

Generated class "CharacterizationTest" in file "CharacterizationTest.php"

For each invocation of the add() function (first argument of the de-legacy-fy command) the data provider will yield a data set that contains the arguments passed to the function as well as the result returned.

The second argument (/tmp/trace.4251619279.xt in the example above) points to the execution trace data file generated by Xdebug. The third and fourth arguments are used to specify the name of test class as well as the file to which its source is to be written.

Here you can see the generated code for our example:

<?php
use PHPUnit\Framework\TestCase;

class CharacterizationTest extends TestCase
{
    /**
     * @return array
     */
    public function provider()
    {
        return [
            [$this->decode('aTozOw=='), $this->decode('aToxOw=='), $this->decode('aToyOw==')]
        ];
    }

    /**
     * @param string $serializedValue
     *
     * @return mixed
     */
    private function decode($serializedValue)
    {
        return unserialize(base64_decode($serializedValue));
    }
}

All that is left for us to do in order to implement the characterization test can be seen below:

<?php
use PHPUnit\Framework\TestCase;

class CharacterizationTest extends TestCase
{
    /**
     * @dataProvider provider
     */
    public function testAddFunctionWorksLikeItUsedTo($expected, $a, $b)
    {
        $this->assertEquals($expected, add($a, $b));
    }

    /**
     * @return array
     */
    public function provider()
    {
        return [
            [$this->decode('aTozOw=='), $this->decode('aToxOw=='), $this->decode('aToyOw==')]
        ];
    }

    /**
     * @param string $serializedValue
     *
     * @return mixed
     */
    private function decode($serializedValue)
    {
        return unserialize(base64_decode($serializedValue));
    }
}

Wrapping a static API class

Static methods are death to testability. It is characteristic for a legacy code base to use global state and static methods. Sometimes there are "library classes" that only contain static methods:

<?php
class Library
{
    public static function doSomething($a, $b)
    {
        // ...
    }
}

The problem with a static method is not that the static method itself is hard to test. The problem is that the code that uses the static method is tightly coupled to the static method, making it impossible to test without also executing the code of the static method.

In the code below, the Library class is an implicit dependency of the Processor class' process() method. It is implicit because it is not obvious from the method's API that it depends on Library. Furthermore, we can not test the process() method in isolation from the doSomething() method.

<?php
class Processor
{
    public function process()
    {
        // ...

        Library::doSomething('...', '...');

        // ...
    }
}

The wrap-static-api command of de-legacy-fy can automatically generate a wrapper class for a static API class such as Library:

$ de-legacy-fy wrap-static-api Library Library.php
de-legacy-fy 2.0.0 by Sebastian Bergmann.

Generated class "LibraryWrapper" in file "LibraryWrapper.php"

<?php
/**
 * Automatically generated wrapper class for Library
 * @see Library
 */
class LibraryWrapper
{
    /**
     * @see Library::doSomething
     */
    public function doSomething($a, $b)
    {
        return Library::doSomething($a, $b);
    }
}

We can now make LibraryWrapper a dependency of Processor:

<?php
class Processor
{
    private $library;

    public function __construct(LibraryWrapper $library)
    {
        $this->library = $library;
    }

    public function process()
    {
        // ...

        $this->library->doSomething('...', '...');

        // ...
    }
}

The Processor class does not use the legacy Library class directly anymore and can be tested in isolation from it (as we can now stub or mock the LibraryWrapper class).

Using the concept of branch-by-abstraction we can now write new code that uses the LibraryWrapper class and migrate old code from Library to LibraryWrapper. Eventually we can reimplement the functionality of Library inside the LibraryWrapper class. Once no code relies on Library anymore we can delete Library and rename LibraryWrapper to Library.

sebastian / de-legacy-fy

Maintainers

Details