8000 [Plugin] Add documentation for the VCR plugin by GaryPEGEOT · Pull Request #262 · php-http/documentation · GitHub
[go: up one dir, main page]
Skip to content

[Plugin] Add documentation for the VCR plugin #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 2, 2019
Merged

[Plugin] Add documentation for the VCR plugin #262

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5ff74f5
Add documentation for the VCR plugin
GaryPEGEOT Mar 31, 2019
6770340
Type fix, add additional info
GaryPEGEOT Apr 1, 2019
fdfd25c
Update wording
GaryPEGEOT Apr 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Type fix, add additional info
  • Loading branch information
@GaryPEGEOT
GaryPEGEOT authored and Gary PEGEOT committed Apr 2, 2019
commit 677034063dc15bebf7c36a3c0281b29edf43c9a8
30 changes: 19 additions & 11 deletions plugins/vcr.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
VCR Plugin
==========
VCR Plugin - Record and Replay Responses
========================================

The VCR plugins allow you to record & replay HTTP responses.
The VCR plugins allow you to record & replay HTTP responses. It's very useful for test purpose (using production-like predictable fixtures and avoid making actual HTTP request).
You can also use it during your development cycle, when the endpoint you're contacting is not ready yet.

Unlike the :doc:`php-http/mock-client </clients/mock-client>`, where you have to manually define responses, the responses are **automatically** generated from the previously recorded ones.

Install
-------
Expand All @@ -22,8 +25,8 @@ The naming strategy turn a request into a deterministic and unique identifier.
The identifier must be safe to use with a filesystem.
The plugin provide a default naming strategy, the ``PathNamingStrategy``. You can define two options:

* **hash_headers**: the list of header names to hash (Ex: Authorization),
* **hash_body_methods**: methods for which the body will be hashed (Default: PUT, POST, PATCH)
* **hash_headers**: the list of header(s) that make the request unique (Ex: 'Authorization'). The content of the header will be hashed to generate a unique signature. By default no header is used.
* **hash_body_methods**: indicate for which request methods the body makes requests distinct. (Default: PUT, POST, PATCH)

This naming strategy will turn a GET request to https://example.org/my-path to the ``example.org_GET_my-path`` name, and optionally add hashes if the request
contain a header defined in the options, or if the method is not idempotent.
Expand All @@ -33,7 +36,7 @@ To create your own strategy, you need to create a class implementing ``Http\Clie
The recorder
************

The recorder records and replays responses. The plugin provide a two recorders:
The recorder records and replays responses. The plugin provides two recorders:

* ``FilesystemRecorder``: Saves the response on your filesystem using Symfony's `filesystem component`_ and `Guzzle PSR7`_ library.
* ``InMemoryRecorder``: Saves the response in memory. **Response will be lost at the end of the running process**
Expand All @@ -46,13 +49,15 @@ To create your own recorder, you need to create a class implementing the followi
The plugins
***********

VCR come built-in with two plugins:
There are two plugins, one to record responses, the other to replay them.

* ``Http\Client\Plugin\Vcr\ReplayPlugin``, use a ``PlayerInterface`` to replay previously recorded responses.
* ``Http\Client\Plugin\Vcr\RecordPlugin``, use a ``RecorderInterface`` instance to record the responses,

Both plugins add a response header to indicate either under which name the response has been stored (RecordPlugin, ``X-VCR-RECORD`` header), or which response name has been used to replay the request (ReplayPlugin, ``X-VCR-REPLAYED`` header).

If you plan on using both plugins at the same time (Replay or Record), the ``ReplayPlugin`` **must always** come first.
Please also note that by default, the ``ReplayPlugin`` throw an exception when it cannot replay a request, unless you set the third constructor argument to ``false`` (See example below).
Please also note that by default, the ``ReplayPlugin`` throws an exception when it cannot replay a request. If you want the plugin to continue the request (possibly to the actual server), set the third constructor argument to ``false`` (See example below).

Example
*******
Expand Down Expand Up @@ -86,11 +91,14 @@ Example
[$replay, $record] // Replay should always go first
);

/** @var \Psr\Http\Message\RequestInterface $request */
$request = new MyRequest('GET', 'https://httplug.io');

// Will be recorded in "some/dir/in/vcs"
$client->sendRequest(//...);
$client->sendRequest($request);

// Will be replayed from "some/dir/in/vcs"
$client->sendRequest(//...);
$client->sendRequest($request);

.. _filesystem component: https://symfony.com/doc/current/components/filesystem.html
.. _Guzzle PSR7: https://github.com/guzzle/psr7
.. _Guzzle PSR7: https://github.com/guzzle/psr7
0