Download the PHP package kshabazz/interception without Composer

Table of Contents

• Introduction
• Requirements
• How it works
• Examples
  • How to save HTTP request for playback during unit test (Manual way)
  • Setup interception unit tests annotations with the InterceptionListener in PHPUnit

Introduction

The purpose of this library is to record the request (1) of URI resources and play them back from local cache. When an interception stream wrapper is registered, for a given protocol, it will handle all URI request for that protocol. Acting as a middleman, the first request will be allowed so that it can be saved locally; this save is then played back for all subsequent calls. Please note that playback is indefinite, until the local cache is deleted, or the interception stream wrapper is unregistered.

The intended use of this library was to aid in mocking/simulating HTTP request during Unit tests runs. By allowing a real request to a service to be saved and played back during unit test. Since this works at the PHP stream level, existing code should only need minimal change, if any.

Beside fopen and file_get_contents, there is also a Guzzle handler which can be used in order for this to work with code that uses Guzzle. See example using (Guzzle ~5.0)[#how-can-i-use-this-with-guzzle]

Disclaimer

This library will only work with PHP streams. Other PHP extensions such as cURL, are not supported.

1. request - consist of the headers and the payload are saved as *.rsd
2. rsd - stand for "raw socket data" file. No encoding is done.

Requirements

• PHP ~5.4
• PHPUnit ~4.7

How it works

The built-in wrapper for the protocol HTTP/HTTPS are first unregistered, then replaced with the Interception StreamWrappers\Http wrapper. Once registered, you must specify a filename using Http::setSaveFilename(), which will be used to save the response to a file with that name. When an HTTP/HTTPS request is made using PHP stream functions fopen() or file_get_contents(), the interception wrapper will then make a TCP connection and return that as a resource for those functions. Once eof() has been called on the resource, a file is saved using the name provided; Which will contain the header and any content retrieved.

A note about fopen(). Unlike file_get_contents(), all content is not read at one time. Only content read using (fread on) the returned TCP resource will be saved to a file once fclose() is called.

Once a filename has been set, all HTTP request will get the response saved in that file. So it is important to remember that if you want a different request, you need to provide a new file name. Or you can restore the default Http functionality by calling stream_wrapper_restore( 'http' ), which will remove the Interception stream wrapper.

Now that you have the response from the request saved, you can use Interceptions Http stream wrapper class (StreamWrappers\Http) to simulated the request. There is nothing else you need to do as long as the StreamWrappers\Http class is registered as PHP stream wrapper handler. Since this is at the stream wrapper layer, it will work for any code that uses PHP Streams.

In cases where this is the first call to a URL, using \fopen, but \foef did not return TRUE; then only partial content will be saved. At minimum the HEADER for the request will be saved.

If two or more request to the same URL are made using \fopen or \file_get_contents, and before any are closed; They will all have independent TCP resources. They will each save a file on \fclose, with the later overwriting the previous save.

Examples

How to save HTTP request for playback during unit test (Manual way)

How to use the Interception test listener with PHPUnit (in a streamlined way)

Interception comes with a PHPUnit test listener which allows you to use annotations with your unit test to simplify saving request. This works as a replacement for the manual way, and automates saving and serving up HTTP request during runs. There requires some additional setup however.

1. Set a constant that points to the path where you want the request to be save. This can be done in your unit test bootstrap file, assuming you have one, like so:

2. In your PHP Unit configuration file, add the listener like so:

3. Now you can write unit test and use the "@interception" annotation.

How can I intercept multiple HTTP(S) request

When use use the InterceptionListener you can intercept multiple HTTP request in a single unit test by using the "@interceptionPersist " annotation. Like so:

Notice each time you make a request, the filename will be appended with the number of the request.

How can I use this with Guzzle

How do I update responses.

1. Delete the *.rsd file in your fixtures directory, so the next time you run tests, a new one will be saved.

Run Unit Test