de-legacy-fy
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 PHPUnitFrameworkTestCase; 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 PHPUnitFrameworkTestCase; 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
.