README.md

Fixture client for PHP-HTTP

This is a fixture client for PHP-HTTP and is meant for testing purposes. It maps requests to static fixtures.

Install

$ composer require --dev swisnl/php-http-fixture-client

Usage

// Create client
$responseBuilder = new \Swis\Http\Fixture\ResponseBuilder('/path/to/fixtures');
$client = new \Swis\Http\Fixture\Client($responseBuilder);

// Send request
$response = $client->sendRequest(new Request(...));

Fixture mapping

All requests send using this client are mapped to static fixtures located in the provided path. URLs are transformed to file paths by using the domain and path fragments and (optionally) the method and/or the query params (sorted alphabetically). A list of possible fixture paths is made and handled in order of specificity:

1. {path}.{query}.{method}.mock
2. {path}.{query}.mock
3. {path}.{method}.mock
4. {path}.mock

Please see the following table for some examples.

URL	Method	Possible fixtures (in order of specificity)
http://example.com/api/articles/1	GET	/path/to/fixtures/example.com/api/articles/1.get.mock
		/path/to/fixtures/example.com/api/articles/1.mock
http://example.com/api/articles	POST	/path/to/fixtures/example.com/api/articles.post.mock
		/path/to/fixtures/example.com/api/articles.mock
http://example.com/api/comments?query=json	GET	/path/to/fixtures/example.com/api/comments.query=json.get.mock
		/path/to/fixtures/example.com/api/comments.query=json.mock
		/path/to/fixtures/example.com/api/comments.get.mock
		/path/to/fixtures/example.com/api/comments.mock
http://example.com/api/comments?query=json&order=id	GET	/path/to/fixtures/example.com/api/comments.order=id&query=json.get.mock
		/path/to/fixtures/example.com/api/comments.order=id&query=json.mock
		/path/to/fixtures/example.com/api/comments.get.mock
		/path/to/fixtures/example.com/api/comments.mock

Domain aliases

The ReponseBuilder can be instructed to use aliases for domains using setDomainAliases([...]). When configured, the provided aliases will be normalized when transforming requests to file paths. You should provide aliases in the form of ['alias' => 'abstract'].

Ignored query parameters

The ReponseBuilder can be instructed to ignore certain query parameters using setIgnoredQueryParameters([...]). When configured, the provided parameters will be ignored when transforming requests to file paths. You should only provide the parameter name, not the value. This allows you to ignore 'dynamic' parameters that change in each test execution. Parameters are matched strictly, after url decoding, so 'foo' will match 'foo=bar', but not 'foo[]=bar'.

Strict mode

The ReponseBuilder can be set to strict mode using setStrictMode(true). When in strict mode, only the first possible fixture path will be used. This means that both the method and query params must be present in the fixture file name and it does not fall back to other fixture files.

Helper

Please see https://swisnl.github.io/php-http-fixture-client/#helper for the URL helper.

Body

The body of a request is loaded directly from a fixture with the file extension .mock. The contents of this file can be anything that is a valid HTTP response, e.g. HTML, JSON or even images. If a fixture can not be found, a MockNotFoundException will be thrown. This exception has a convenience method getPossiblePaths() which lists all file paths that were checked, in order of specificity.

Headers (optional)

The headers of a request are loaded from a fixture with the file extension .headers. This is a simple JSON object with headers, e.g.

{
  "X-Made-With": "PHPUnit"
}

Status (optional)

The status code of a request is loaded from a fixture with the file extension .status. This is a plain file containing only the HTTP status code. If no .status file is found, 200 OK will be used.

Mocks (advanced)

This client extends php-http/mock-client, which allows you to add custom responses and exceptions that ignore fixture files. Please see the mock-client documentation for more information.

N.B. A default response can not be set because this client uses that under the hood.

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

SWIS ❤️ Open Source

SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.