sebastianbergmann/de-legacy-fy

Tool for dealing with legacy PHP code

de-legacy-fy

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.

de-legacy-fy's Issues

Add support for parsing multiple execution traces to CharacterizationTestGenerator

Execution trace data file must be in format version 4 (or later)

Hello,

I am using the example arguments and I can't seem to generate a format version 4 trace file.

I originally tried xdebug 2.2.5.

I built xdebug 2.2.7 from source and tried that as well.

I could not find any xdebug documentation explaining how the format version is determined. This is what I tried:

//test.php
<?php
echo "hello world!";

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

cat /tmp/trace.2362852153.xt
Version: 2.2.7
File format: 2
TRACE START [2015-02-13 21:08:30]
1   0   0   0.000113    222208  {main}  1       /var/www/7.1-Branch/tests/characterization/generate/test.php    0   0
1   0   1   0.000394    222288
            0.000697    8240
TRACE END   [2015-02-13 21:08:30]

My current ini: https://gist.github.com/matthew-james/795dd4a6939c41ff2217

Thanks!
-Matt

typo in readme?

I have helped many a team

Add support for namespaces

Hello Sebastian,

While I wanted to implement some tests on our legacy code that used static classes/methods as clearly explained in documentation, I've discovered that the namespace is not really supported.

Invoking following command

$ php de-legacy-fy-1.0.2.phar wrap-static-api Name_Space\\ClassName /path/to/source/file

Will generate something like

<?php
/**
 * Automatically generated wrapper class for Name_Space\ClassName
 * @see Name_Space\ClassName
 */
class Name_Space\ClassNameWrapper

Expected result could be

<?php
namespace Name_Space;

/**
 * Automatically generated wrapper class for Name_Space\ClassName
 * @see Name_Space\ClassName
 */
class ClassNameWrapper

BTW, nice tool, very usefull :)

Refactor StaticApiWrapper to use PHP-Parser instead of Reflection API

Move XdebugTraceParser to a separate component (and make it more generic)

Idea: use overlay filesystem to trace/record file io.

I was thinking of using docker and its overaly FS to record the changes of rather hefty function I need to characterize. The function has a lot of side-effects in the form of file IO. What would your approach be for this. If you have an approach, would the ability to trace file IO be a good fit for de-legacy-fy? In the same vein, network IO would be nice to have too.

I'm willing to contribute, just hoping you can nudge me in the right direction.