Download the PHP package darkmatus/phiremock-server without Composer

Phiremock Server

Phiremock is a mocker and stubber of HTTP services, it allows software developers to mock HTTP requests and setup responses to avoid calling real services during development, and is particulary useful during acceptance testing when expected http requests can be mocked and verified. Any HTTP service (i.e.: REST services) can be mocked and stubbed with Phiremock.

Phiremock is heavily inspired by WireMock, but does not force you to have a java installation in your PHP development environment. The full functionality of Phiremock is detailed in the following list:

• Allows to mock http request based in method, headers, url, body content and form fields.
• Allows to match expectations using several comparison functions.
• REST interface to setup.
• Stateful and stateless mocking through scenarios.
• Network latency simulation.
• Priorizable expectations for cases in which more than one matches the request. If more than one expectation matches the request and no priorities were set, the first match is returned.
• Allows to verify the amount of times a request was done.
• Allows to load default expectations from json files in a directory tree.
• Proxy requests to another URL as they are received.
• Fill the response body using data from the request.
• Integration to codeception through phiremock-codeception-extension and phiremock-codeception-module.
• Client with nice API supporting all functionalities: phiremock-client

Installation

Default installation through composer

Phiremock Server requires guzzle client v6 to work. This dependency can be avoided and you can choose any psr18-compatible http client and overwrite Phiremock Server's factory to provide it.

Phar

You can also download the standalone server as a phar from here.

Running

Execute ./vendor/bin/phiremock.

Command line arguments

• --ip|-i - Network interface where to listen for http connections. Default: 0.0.0.0
• --port|-p - Port where to listen for http connections. Default: 8086
• --expectations-dir|-e - Directory where to search for predefined static expectations. Default: [HOME_PATH]/.phiremock/expectations
• --factory-class|f - Factory class to use to create the objects needed by phiremock server. Default: Default internal factory class.
• --certificate|t - Certificate file to enable phiremock to listen for secure connections (https).
• --certificate-key|k - Path to the certificate key.
• --cert-passphrase|s - Passphrase to use if the certificate is encrypted.
• --debug|-d - Flag to activate the debug mode.

Note: Static expectations saved in files are very useful if you use phiremock in your development environment. For testing, can be more useful to setup expectations on the fly.

Note: When a certificate is added, phiremock-server will only listen for secure connections.

Configuration

You can statically specify phiremock server's configuration in the .phiremock file. It looks as following:

This file will be searched as following, the first one found is the one to use:

1. PROJECT_ROOT_DIR/.phiremock (if installed under /vendor)
2. PROJECT_ROOT_DIR/.phiremock.dist (if installed under /vendor)
3. PHIREMOCK_ROOT_DIR/.phiremock (if pulled standalone)
4. PHIREMOCK_ROOT_DIR/.phiremock.dist (if pulled standalone)
5. $CWD/.phiremock
6. $CWD/.phiremock.dist
7. $HOME/.phiremock/config
8. .phiremock (uses php's include path)
9. .phiremock.dist(uses php's include path)

Note: The command line arguments have higher priority over the options in the config file, so they will override them if provided.

Overwriting the factory class

If guzzle client v6 is provided as a dependency no extra configuration is needed. If you want to use a different http client you need to provide it to phiremock server as a psr18-compatible client. For instance, if you want to use guzzle client v7 you need to extend phiremock server's factory class:

Then provide the fully qualified class name to phiremock-server using the command line options or the configuration file.

Note: This will only work if phiremock is instaled through composer, since it will use the same vendor folder and autoloader as your project. Also if you pull phiremock repo and extend the composer.json file.

How does it work?

Phiremock will allow you to create a stubbed version of some external service your application needs to communicate to. That can be used to avoid calling the real application during development or to setup responses to expected requests. To do this, you need to trick your application to request phiremock server when on development stage or testing stage.

Setup your application's configuration

First of all you need to setup the config for the different environments for your application. For instance:

Configure expectations

Then, using phiremock's REST interface, expectations can be configured, specifying the response to send for a given request. A REST expectation resource for phiremock looks like this:

The same format can be used in expectation files saved in the directory tree specified by the --expectations-dir argument of the CLI. For Phiremock Server to be able to load them, each file should have .json extension. For instance: match-all-images.json for the previous example.

Features

Create an expectation

To create previous response from code the following should be used:

Clear expectations

After a test runs, all previously configured expectations can be deleted so they don't affect the execution of the next test:

List all expectations

If you want, for some reason, list all created expectations. A convenient endpoint is provided:

Verify amount of requests

To know how much times a request was sent to Phiremock Server, for instance to verify after a feature execution in a test, there is a helper method too:

Search executed requests

To search for the list of requests to which Phiremock Server responded:

Reset requests log

To reset the requests counter to 0, Phiremock Server also provides an endpoint:

Reset Phiremock to its initial state

This call will clean the requests list, the scenarios, delete all configured expectations and reload the static ones defined in the expectations directory.

Cool stuff

Send binary body in response

Binary contents can be sent as a response body too by encoding it as base64 in the expectation json.

Priorities

Phiremock accepts multiple expectations that can match the same request. If no priorities are set, it will match the first expectation created but, if you need to give high priority to some request, you can do it easily.

Suppose you have the next two expectations configured:

In the previous example, both expectations will match a request with url equal to: /example_service/some/resource and method GET. But Phiremock will give higher priority to the one with the Accept header equal to application/json. Default priority for an expectation is 0, the higher the number, the higher the priority.

Stateful behaviour

If you want to simulate a behaviour of the service in which a response depends of a state that was set in a previous request. You can use scenarios to create a stateful behaviour.

In this case, the first time that Phiremock Server receives a request matching the expectation, the first one will match and it will change the state of the saved scenario. From the second time the same request is executed, the second expectation will be matched. If you want after the second call, to go back to the initial state just add "newScenarioState": "Scenario.START" to the then section.

To reset all scenarios to the initial state (Scenario.START) use this simple method from the client:

To define a scenario state in any moment:

Netwok latency simulation

If you want to test how your application behaves on, for instance, a timeout; you can make Phiremock to delay the response of your request as follows.

This will cause Phiremock Server to wait 30 seconds before sending the response.

Proxy

It could be the case that a mock is not needed for certain call. For this specific case, Phiremock provides a proxy feature that will pass the received request unmodified to a configured URI and return the real response from it. It can be configured as folows:

In this case, Phiremock will POST http://your.real.service/some/path/script.php with the configured body and header and return it's response.

Compare JSON objects

Phiremock supports comparing strict equality of json objects, in case it's used in the API. The comparison is object-wise, so it does not matter that indentation or spacing is different.

Generate response based in request data

It could happen that you want to make your response dependent on data you receive in your request. For this cases you can use regexp matching for request url and/or body, and access the subpatterns matches from your response body specification using ${body.matchIndex} or ${url.matchIndex} notation.

Also retrieving data from multiple matches is supported:

Conditions based in form data

For requests encoded with application/x-www-form-urlencoded and specifying this Content Type in the headers. Phiremock Server is capable of execute conditions on the values of the form fields.

Backwards compatibility

Phiremock Server still supports expectations in the format of Phiremock V1. This should make your migration from Phiremock v1 to Phiremock v1 (phiremock-server + phiremock-client) easier.

Appendix

List of condition matchers:

• contains: Checks that the given section of the http request contains the specified string.
• isEqualTo: Checks that the given section of the http request is equal to the one specified, case sensitive.
• isSameString: Checks that the given section of the http request is equal to the one specified, case insensitive.
• matches: Checks that the given section of the http request matches the regular expression specified.
• isSameJsonObject: Checks that json received in the request is the same as a given JSON.

See also

• Phiremock Client: https://github.com/mcustiel/phiremock-client
• Phiremock Codeception Extension: https://github.com/mcustiel/phiremock-codeception-extension
• Examples in tests: https://github.com/mcustiel/phiremock-server/tree/master/tests/acceptance

Contributing:

Just submit a pull request. Don't forget to run tests and php-cs-fixer first and write documentation.

Thanks to:

• Denis Rudoi (@drudoi)
• Henrik Schmidt (@mrIncompetent)
• Nils Gajsek (@linslin)
• Florian Levis (@Gounlaf)

And everyone who submitted their Pull Requests.