Download the PHP package sebastian/de-legacy-fy without Composer

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:

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

Composer

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

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:

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:

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

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

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:

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

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:

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.

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

We can now make LibraryWrapper a dependency of Processor:

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.