Record and replay for testing of legacy PHP applications

So you've got this big ball of code. You don't even know how to call all of these scripts, but the code is in production and works just fine (until you have to change even a single line). How to define some characterization tests that describe how the .php scripts work now? This is an essential task to avoid breaking things, but most of the time the parameters of the scripts and their response is not documented at all (or it is documented incorrectly.)

The bunch of .php files

The typical legacy application does not have a single entry point: there is no single index.php which gathers all requests, but many different files, each taking some arguments. When these files are linked to in many places, or called from external services, it becomes not trivial to define their behavior. If tests do not exist, we do not know if they expect GET or POST requests, which parameters they contain, and above all what their response should be in correct and error cases.

Even if all the links and calling code are under your control, it may be faster to go for the recording approach. If other applications and machines call your .php files, it is your only choice.

Our goals

When recording the behavior of all the different entry points of a legacy PHP application, our aim is to build a comprehensive list of request and response examples, and of the side effects that they cause.

For example, SQL UPDATE queries are a kind of side effect, along with any file written during execution. While request and response recording is fairly standard in PHP, the side effect part varies wildly depending on the application.

The input parameters of a .php script are:

• $_GET: every parameter passed to the index.php query string.
• $_POST: every parameter passed in a POST request, when applicable.
• $_SERVER: information on headers and on the remote ip address that has made the request.
• HTTP request headers, such as User-Agent or Authentication.

In case you accept PUT requests, you should record their content (read from standard input).

The output parameters of a script are instead:

• the HTTP response code and set of headers.
• the body of the response.

Furthermore, we also have to record side effects, in the form of method calls (assuming there is some kind of service layer between the script and the rest of the application, even in the form of procedural functions).

How to record

ob_start() enables the output buffering capabilities of PHP: the response will be buffered instead of being immediately sent. We can pass a callback to this function which will be called at the end of the script to log the response.

Here are other examples of global black magic to record a PHP's script execution:

• the $_GET and $_POST superglobal variables are available in any scope, along with $_SERVER.
• headers_list() obtains the response headers under Apache, but not the response code. You should log it on your own if you set it.

By the way, getallheaders() or its equivalent apache_request_headers() are not very reliable for gathering request headers, as they are Apache-dependent, and rely on PHP being installed as an Apache module. The PHP manual suggests to use portable CGI variables like $_SERVER, but you'll have to parse the header names yourself.

Thus even without an object graph or seams of any kind to insert the recording logic, PHP offers these hooks to store pairs of real request and responses for further study.

An abstraction: the Tape object

Back in the days, you bought empty tapes to record from the radio or the television. So while working on recording I introduced a Tape class.

At the start of each script I instantiated a new Tape and told it to record.

// the name of the script is a parameter of the log filename which is written
$tape = new Tape(__FILE__);
// the callback for registering the response
ob_start(array($tape, 'record'));

Public methods on $tape were available for storing interesting objects and other variables when needed during the script. For example, a side-effect like an SQL query should be saved with $tape->export($statement).

If you're writing a single log file for each script, which is my advice, you'll need a way to correlate request, responses and other information. For this purpose, my Tape class generate a unique label for each object:

$this->label = uniqid('tape');

and every time you call:

$tape->export('varname', $variable);

a new log line will be written as:

tape01234... varname "content"

with var_export() and file_put_contents() with the FILE_APPEND flag set.

Conclusions

Once you know what your legacy .php files are actually doing on the production server, you can start writing tests for the next step: getting them covered. But at least you have a clear picture of input, output and side effects of each of them: you don't have to wonder about which query string parameter is necessary to avoid a Fatal Error or if the new database query is equivalent to the existing ones.