Guzzle Stereo
Record and Replay HTTP Responses easily., (*1)
, (*2)
Requirements
Installation
Require the composer package :, (*3)
composer require ikwattro/guzzle-stereo
NB: If you're using the Symfony Framework, you can take a look at the GuzzleStereoBundle from @estahn., (*4)
Basics
Recorder
A recorder is the main object that knows everything about tapes and how to store them afterwards., (*5)
Tapes
A tape will record Response objects. It has a name and can have filters. A filter can tell for example that only
Responses with a 200 status code will be recorded in that tape., (*6)
Defining tapes and filters is done through a yaml file definition :, (*7)
tapes:
my_tape:
filters:
status_code: 200
This tape will record only success responses., (*8)
Filters
A filter is a rule telling if the Response object should be included or not. There is a set of built-in filters available
with the library or you can create your own and register them., (*9)
NB: If you feel that your filter can be generic enough, do not hesitate to open a PullRequest, (*10)
Store directory
In order to be replayed later (see the Replay section below), all tapes will then be dumped in json files to disk. You need
to provide a writable directory., (*11)
Player
A player is able to replay dumped json files as Response objects. A nice use case is to replay them with a Mock Handler in
your test suites., (*12)
Usage
Recording
Instantiate the recorder by providing a writable store directory and the location of your tapes definitions file :, (*13)
require_once(__DIR__.'/vendor/autoload.php');
use Ikwattro\GuzzleStereo\Recorder;
$recorder = new Recorder(__DIR__.'/var/records', __DIR__.'/stereo.yml');
Next, when creating your Guzzle client, you need to make him aware of the recorder. An easy way to do this is by using a Middleware
available with the library :, (*14)
$stack = \GuzzleHttp\HandlerStack::create();
$stack->push(\Ikwattro\GuzzleStereo\RecorderMiddleware::record($recorder));
$client = new \GuzzleHttp\Client(['handler' => $stack]);
You can now make http requests with the Client as you would usually do, for e.g. here we'll call the Github events API 10 times :, (*15)
for ($i = 0; $i < 10; $i++) {
try {
$client->get('https://api.github.com/events');
} catch (RequestException $e) {
// Do what you want
}
}
Finally, you'll need to tell the recorder to dump the tapes to the disk :, (*16)
$recorder->dump();
A file named record_ + {tape_name} will be created in the provided store directory containing the responses passing the filters :, (*17)
Replaying
In order to replay the recorded tapes, you can use the Player. The player is in fact creating a Mock Handler and will return you
a GuzzleHttp\Client instance created with the MockHandler containing the responses from the tape file., (*18)
use Ikwattro\GuzzleStereo\Player;
$player = Player::replayFromTape('/path/to/tape.json');
$player->get('/');
// will return you the first response record present in the tape
Filters reference
StatusCode
Include the Response only if it has the corresponding status code., (*19)
tapes:
my_tape:
filters:
status_code: 200
Non Empty Body
Include the Response only if the body is not empty., (*20)
tapes:
my_tape:
filters:
non_empty_body: ~
Include the Response only if she contains a header with the specified key., (*21)
tapes:
my_tape:
filters:
has_header: "Content-Type"
Creating your own filters
Creating a filter is really easy. You need to create a filter class implementing Ikwattro\GuzzleStereo\Filter\FilterInterface and
declaring the two methods :, (*22)
public static function getName()public function isIncluded(ResponseInterface $response)
The getName static function is responsible for defining the name of the filters in your tapes., (*23)
The isIncluded function will contain the logic determining if the received Response should be included or not in the Tape., (*24)
The following example filter will receive a response from the Github events api, and will record it only if the body contains
an event done by the Github users you will pass as arguments when associating your filter to a tape., (*25)
<?php
namespace Acme\MyApp\Filter;
use Ikwattro\GuzzleStereo\Filter\FilterInterface;
use Psr\Http\Message\ResponseInterface;
class ActorFilter implements FilterInterface
{
const FILTER_NAME = "actor_filter";
protected $users;
public function__construct(array $users = array())
{
$this->users = $users;
}
public static function getName()
{
return self::FILTER_NAME;
}
public function isIncluded(ResponseInterface $response)
{
$body = json_decode((string) $response->getBody());
foreach ($body as $event) {
$actor = $event['actor']['login'];
if (in_array($actor, $this->users)) {
return true;
}
}
return false;
}
}
You can now add your custom filter in your configuration and use it in your tapes :, (*26)
custom_filters:
- "Acme\MyApp\Filter\ActorFilter"
-
tapes:
my_tape:
filters:
actor_filter: ["jexp","ikwattro","luanne"]
Your tape will now contain only Responses that included in their actors one of the provided actors., (*27)
Your Responses objects can contain a specific header as a marker by setting the following configuration flag :, (*28)
marker_header: true
which will add a X-Guzzle-Stereo header with a true value., (*29)
TODO
- more filters
- blacklists
- null tape
- better configuration management (maybe Symfony config component)
- combined requestAndResponses
- filter what should be returned from the player
- your ideas ?
Tests
phpspec and phpunit are used for the tests:, (*30)
./vendor/bin/phpspec run -f pretty
./vendor/bin/phpunit
License
The library is issued under the MIT license, please refer to the LICENSE file provided with the package., (*31)
Contribute
Feel free to contribute or report issues on Github., (*32)
Author
Christophe Willemsen, (*33)
Twitter: @ikwattro, (*34)
Github: @ikwattro, (*35)
Wallogit.com
