Phiremock

https://github.com/mcustiel/phiremock
Admin
Phiremock is a PHP mocker and stubber for HTTP services that allows developers to mock HTTP...
Tokens:50,787
Snippets:385
Trust Score:9.2
License:GPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run Phiremock server with CLI options

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server.md

Example command to start the Phiremock server, specifying the IP, port, expectations directory, and debug mode.

```bash
./vendor/bin/phiremock -i 0.0.0.0 -p 8086 -e ./expectations --debug
```

--------------------------------

### Full example using only helper functions

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Shows how to create an expectation using the global helper functions: on, getRequest, contains, isEqualTo, and respond. The example sets a condition on the request body and header, and responds with status 418 and body 'no'.

```php
use Mcustiel\Phiremock\Client\Phiremock;
use function Mcustiel\Phiremock\Client\contains;
use function Mcustiel\Phiremock\Client\getRequest;
use function Mcustiel\Phiremock\Client\isEqualTo;
use function Mcustiel\Phiremock\Client\on;
use function Mcustiel\Phiremock\Client\respond;

$phiremock->createExpectation(
    on(getRequest('/potato/tomato')
        ->andBody(contains('42'))
        ->andHeader('Accept', isEqualTo('application/banana')))
        ->then(respond(418)->andBody('no'))
);
```

--------------------------------

### Factory usage example with error paths

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Usage example for creating an expectation converter via the Factory. Shows the normal flow with version 2 and error paths for unimplemented version and unknown options, which throw exceptions.

```php
use Mcustiel\Phiremock\Factory;

$factory = new Factory();
$converter = $factory->createArrayToExpectationConverterLocator()
    ->locate(['version' => '2', 'on' => [], 'then' => ['response' => ['statusCode' => 204]]]);
$expectation = $converter->convert(['version' => '2', 'on' => [], 'then' => ['response' => ['statusCode' => 204]]]);

// error paths:
// $locator->locate(['version' => '3'])              -> \Exception 'Unimplemented configuration version: 3'
// $factory->createV2UtilsFactory()->createArrayToExpectationConverter()
//     ->convert(['bogus' => 1])                     -> \Exception 'Unknown expectation options: ...'
```

--------------------------------

### Phiremock configuration file example (.phiremock)

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/configuration.md

Example configuration file for Phiremock. Returns a PHP array with the valid keys: port, ip, expectations-dir, debug, and factory-class. Note that additional keys (e.g., certificate options) trigger a DomainException in this code path.

```php
<?php
// .phiremock — returns the config array
return [
    'port'             => 8086,
    'ip'               => '0.0.0.0',
    'expectations-dir' => $_SERVER['HOME'] . '/.phiremock/expectations',
    'debug'            => false,
    'factory-class'    => '\\My\\Namespace\\FactoryClass',
];
```

--------------------------------

### listExpectations(): array

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Retrieves a list of all expectations currently installed on the Phiremock server.

```APIDOC
## listExpectations(): array

### Description
Retrieves a list of all expectations currently installed on the Phiremock server.

### Method
GET

### Endpoint
/__phiremock/expectations

### Response
#### Success Response (200)
- **body** (array) - An array of `Mcustiel\Phiremock\Domain\Expectation` objects, deserialized through `ArrayToExpectationConverter`.

### Example
```php
$expectations = $phiremock->listExpectations();
```
```

--------------------------------

### CLI Command: run

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server.md

Documentation for the Phiremock server CLI command 'run', including its options and usage example.

```APIDOC
## CLI Command: run

### Description
Starts the Phiremock HTTP server. This is the default command of the `bin/phiremock` binary.

### Usage
```bash
./vendor/bin/phiremock [options]
```

### Options
| Option | Short | Requires value | Description |
|--------|-------|---------------|-------------|
| `--ip` | `-i` | yes | IP address of the interface where Phiremock must listen for connections |
| `--port` | `-p` | yes | Port where Phiremock must listen for connections |
| `--expectations-dir` | `-e` | yes | Directory in which to search for expectation definition files |
| `--debug` | `-d` | no (flag) | Sets debug mode |
| `--config-path` | `-c` | yes | Directory in which to search for configuration files. Default: current directory |
| `--factory-class` | `-f` | yes | Factory class to use. It must inherit from `Mcustiel\Phiremock\Server\Factory\Factory` |
| `--certificate` | `-t` | yes | Path to the local certificate for secure connection |
| `--certificate-key` | `-k` | yes | Path to the local certificate key for secure connection |
| `--cert-passphrase` | `-s` | yes | Passphrase if the local certificate is encrypted |

### Example
```bash
./vendor/bin/phiremock -i 0.0.0.0 -p 8086 -e ./expectations --debug
```

### Exit Code
Returns 0 on successful execution.
```

--------------------------------

### ConditionsBuilder usage example

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Example of building request conditions with ConditionsBuilder. Uses create() with method and URL, then adds header, body, JSON path, and scenario state conditions. The resulting builder is used with Phiremock::on() to compose Expectation objects.

```php
use Mcustiel\Phiremock\Client\Utils\ConditionsBuilder;
use Mcustiel\Phiremock\Client\Utils\Is;

$request = ConditionsBuilder::create('POST', '/users')
    ->andHeader('Content-Type', Is::equalTo('application/json'))
    ->andBody(Is::sameJsonObjectAs(['name' => 'potato']))
    ->andJsonPath('a.b.c', Is::equalTo(42))
    ->andScenarioState('login', 'done');
```

--------------------------------

### public static on(ConditionsBuilder $requestBuilder): ExpectationBuilder

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Starts the fluent expectation DSL.

```APIDOC
## public static on(ConditionsBuilder $requestBuilder): ExpectationBuilder

### Description
Starts the fluent expectation DSL. Returns an ExpectationBuilder whose then()/thenRespond() produce a ready-to-send Expectation. See phiremock-client-builders.md for more details.

### Parameters
#### Path Parameters
- **requestBuilder** (ConditionsBuilder) - Required - Request side of the expectation.

### Returns
ExpectationBuilder
```

--------------------------------

### GET /__phiremock/gui

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/endpoints.md

Returns the GUI for the mock server. This endpoint serves the web-based GUI for managing the mock server.

```APIDOC
## GET /__phiremock/gui

### Description
Returns the GUI for the mock server. This endpoint serves the web-based GUI for managing the mock server.

### Method
GET

### Endpoint
/__phiremock/gui

### Response
#### Success Response (200)
- **html** (string) - Description not provided in source.

#### Response Example
{
  "html": "<html>...</html>"
}
```

--------------------------------

### Port usage example with invalid values

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-factory.md

Shows creating a Port with 8086 and comments indicating that 0 and 70000 throw InvalidArgumentException.

```php
use Mcustiel\Phiremock\Client\Connection\Port;

$port = new Port(8086);
// new Port(0)          -> InvalidArgumentException
// new Port(70000)      -> InvalidArgumentException
```

--------------------------------

### GET /__phiremock/expectations

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/endpoints.md

Lists all expectations currently configured in the mock server.

```APIDOC
## GET /__phiremock/expectations

### Description
Lists all expectations currently configured in the mock server.

### Method
GET

### Endpoint
/__phiremock/expectations

### Response
#### Success Response (200)
- **expectations** (array) - Description not provided in source.

#### Response Example
{
  "expectations": []
}
```

--------------------------------

### Phiremock::onRequest example

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Creates an expectation for a GET request to '/status' and configures a 503 response with body 'down'. Equivalent to Phiremock::on(ConditionsBuilder::create($method, $url)).

```php
$expectation = Phiremock::onRequest('GET', '/status')
    ->thenRespond(503, 'down');
```

--------------------------------

### GET /__phiremock/gui

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server-actions.md

Documentation for the GET /__phiremock/gui endpoint that serves the GUI HTML page.

```APIDOC
## GET /__phiremock/gui

### Description
Returns the bundled GUI HTML page for Phiremock. This endpoint serves the static GUI resource to the client.

### Method
GET

### Endpoint
/__phiremock/gui

### Response
#### Success Response (200)
- Content-Type: text/html; charset=utf-8
- Body: The bundled `resources/gui.html` file content.

#### Error Handling
- Throws `RuntimeException` with message `Unable to read GUI HTML resource from %s` if the resource is unreadable.
```

--------------------------------

### Create expectation with thenRespond

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Creates an expectation for a GET request to '/hello' that responds with status 200 and body 'Hello world!'. Uses Phiremock::onRequest and thenRespond.

```php
use Mcustiel\Phiremock\Client\Phiremock;

$phiremock->createExpectation(
    Phiremock::onRequest('GET', '/hello')
        ->thenRespond(200, 'Hello world!')
);
```

--------------------------------

### Using Respond::withStatusCode

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Example of building a response with status 418, body 'teapot', header 'X-Potato: yes', scenario state 'served', and a 150 ms delay. Throws InvalidArgumentException if status code is not 100..599 or delay validation fails.

```php
use Mcustiel\Phiremock\Client\Utils\Respond;

$response = Respond::withStatusCode(418)
    ->andBody('teapot')
    ->andHeader('X-Potato', 'yes')
    ->andSetScenarioStateTo('served')
    ->andDelayInMillis(150);
```

--------------------------------

### Url class methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-http.md

Constructor requires a value matching the URL path pattern (must start with '/', optionally with query/fragment). Throws InvalidArgumentException with message 'Invalid http url: %s' when the value does not match. Empty strings fail.

```php
public const URL_PATH_REGEX = '~^/(?:[^/?#]*)?(?:[^?#]*)(?:\?(?:[^#]*))?~';
public function __construct(string $url)        // pattern must match; empty strings fail
public function asString(): string
public function equals(self $other): bool
```

--------------------------------

### Set priority on expectation

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Creates an expectation for a GET request to '/slow' and sets its priority to 10 before sending. The priority takes precedence over priority-0 expectations.

```php
use Mcustiel\Phiremock\Domain\Options\Priority;

$expectation = Phiremock::onRequest('GET', '/slow')
    ->thenRespond(200, 'ok');
$expectation->setPriority(new Priority(10)); // takes precedence over priority-0 expectations
$phiremock->createExpectation($expectation);
```

--------------------------------

### Usage example with HeadersCollection, StatusCode and error path

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-http.md

Shows how to build a HeadersCollection, set a Content-Type header, create a StatusCode, and handle an invalid status code that throws InvalidArgumentException with the message 'Invalid status code: 999'.

```php
use Mcustiel\Phiremock\Domain\Http\Header;
use Mcustiel\Phiremock\Domain\Http\HeaderName;
use Mcustiel\Phiremock\Domain\Http\HeaderValue;
use Mcustiel\Phiremock\Domain\Http\HeadersCollection;
use Mcustiel\Phiremock\Domain\Http\StatusCode;

$headers = new HeadersCollection();
$headers->setHeader(new Header(new HeaderName('Content-Type'), new HeaderValue('application/json')));
$status = new StatusCode(201);

// error path:
try {
    new StatusCode(999);            // throws InvalidArgumentException
} catch (\InvalidArgumentException $e) {
    // 'Invalid status code: 999'
}
```

--------------------------------

### v2 Expectation JSON example (example-v2.json)

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/types.md

Complete v2 expectation JSON showing scenario, matchers, response, and delay. The 'on' block uses matcher-map form for method, url, body, headers, formData, and jsonPath. The 'then' block includes delayMillis, newScenarioState, and response. Absent 'then' yields HttpResponse(200).

```json
{
  "version": "2",
  "scenarioName": "potato",
  "priority": 1,
  "on": {
    "scenarioStateIs": "Scenario.START",
    "method": {"isSameString": "GET"},
    "url": {"isEqualTo": "/some/thing"},
    "body": {"contains": "hello"},
    "headers": {"Content-Type": {"isEqualTo": "text/plain"}},
    "formData": {"name": {"isEqualTo": "potato"}},
    "jsonPath": {"a.b.c": {"isEqualTo": 42}}
  },
  "then": {
    "delayMillis": 150,
    "newScenarioState": "tomato",
    "response": {
      "statusCode": 200,
      "body": "Hello world!",
      "headers": {"Content-Type": "text/plain"}
    }
  }
}
```

--------------------------------

### clearExpectations(): void

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Removes all currently installed expectations from the Phiremock server. After this operation, non-admin requests will return 404.

```APIDOC
## clearExpectations(): void

### Description
Removes all currently installed expectations from the Phiremock server. After this operation, non-admin requests will return 404.

### Method
DELETE

### Endpoint
/__phiremock/expectations

### Response
#### Success Response (200)
No content.

### Example
```php
$phiremock->clearExpectations();
```
```

--------------------------------

### ConditionValue constructor and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-conditions.md

ConditionValue wraps a raw value and provides asString() for string conversion and get() for the raw value.

```php
public function __construct($value)      // mixed, stored as-is
public function asString(): string       // (string) $value
public function get()                    // mixed, raw value
```

--------------------------------

### Body class constructor and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-http.md

Defines the Body value object with a constructor that takes a string body. Provides methods to check if the body is text, create an empty body, get the body as a string or PSR-7 stream, and compare with another Body instance.

```php
public function __construct(string $body)
public function isTextBody(): bool                     // true
public static function createEmpty(): self             // new self('')
public function asString(): string
public function asStream(): StreamInterface            // PSR-7 stream (Common\StringStream)
public function equals(self $other): bool
```

--------------------------------

### v1 Expectation JSON Example

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/types.md

Complete example of a v1 expectation JSON object. The version field is optional and defaults to '1' when absent. The request object is required; if missing, an InvalidArgumentException 'Expectation request is not set' is thrown. An empty request object acts as a catch-all. Response defaults to 200 with empty body when both response and proxyTo are absent. Unknown top-level keys throw 'Unknown expectation options: …' and unknown request.* keys throw 'Unknown request conditions: …'.

```json
{
  "version": "1",
  "scenarioName": "potato",
  "scenarioStateIs": "Scenario.START",
  "newScenarioState": "tomato",
  "priority": 1,
  "request": {
    "method": "GET",
    "url": {"isEqualTo": "/some/thing"},
    "body": {"contains": "hello"},
    "headers": {"Content-Type": {"isEqualTo": "text/plain"}},
    "formData": {"name": {"isEqualTo": "potato"}}
  },
  "response": {
    "statusCode": 200,
    "body": "Hello world!",
    "headers": {"Content-Type": "text/plain"},
    "delayMillis": 1000
  },
  "proxyTo": null
}
```

--------------------------------

### GET /__phiremock/expectations response

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/endpoints.md

Response body for GET /__phiremock/expectations. Returns a JSON array of expectation objects, each serialized in its own dialect and carrying a version field.

```json
[{"version":"2","scenarioName":null,"on":{...},"then":{...},"priority":0}]
```

--------------------------------

### Static Helper Entry Points

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Static helper classes provide entry points for building conditions and responses.

```APIDOC
## Static Helper Entry Points

### A
- `getRequest(): ConditionsBuilder`
- `postRequest(): ConditionsBuilder`
- `putRequest(): ConditionsBuilder`
- `optionsRequest(): ConditionsBuilder`
- `headRequest(): ConditionsBuilder`
- `fetchRequest(): ConditionsBuilder`
- `deleteRequest(): ConditionsBuilder`
- `patchRequest(): ConditionsBuilder`
- `linkRequest(): ConditionsBuilder`

All return `ConditionsBuilder::create(<METHOD>)`.

### Is
- `equalTo($value): Equals`
- `matching($value): RegExp` - Validates the regex.
- `sameStringAs($value): CaseInsensitiveEquals`
- `containing($value): Contains`
- `sameJsonObjectAs($value): JsonEquals` - Non-string JSON values are json_encoded.

### Respond
- `withStatusCode(int $status): HttpResponseBuilder`

### Proxy
- `to(string $url): ProxyResponseBuilder` - Validates the URL.

```

--------------------------------

### HttpResponseBuilder methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Lists the constructor, factory, body, header, and build methods. andBinaryBody wraps the string in BinaryBody with the phiremock.base64: prefix. build() merges base options into a HttpResponse.

```php
public function __construct(StatusCode $statusCode)
public static function create(int $statusCode): HttpResponseBuilder
public function andBody(string $body): HttpResponseBuilder
public function andBinaryBody(string $body): HttpResponseBuilder
public function andHeader(string $header, string $value): HttpResponseBuilder
public function build(): Response     // @return Response|HttpResponse
```

--------------------------------

### GET /__phiremock/expectations

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server-actions.md

Lists all stored expectations. Returns a JSON array of expectation arrays with Content-Type application/json.

```APIDOC
## GET /__phiremock/expectations

### Description
Lists all stored expectations. Returns a JSON array of expectation arrays with Content-Type application/json.

### Method
GET

### Endpoint
/__phiremock/expectations

### Response
#### Success Response (200)
- **body** (array) - JSON array of expectation arrays.
- **Content-Type** (string) - `application/json`

#### Response Example
```json
[
  {
    "id": 1,
    "request": {},
    "response": {}
  }
]
```
```

--------------------------------

### Create Phiremock client with Factory

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Creates a Phiremock client using the default factory, connecting to localhost on port 8086. This is the recommended way to instantiate the client instead of building it manually.

```php
use Mcustiel\Phiremock\Client\Factory;
use Mcustiel\Phiremock\Client\Connection\Host;
use Mcustiel\Phiremock\Client\Connection\Port;

$phiremock = Factory::createDefault()->createPhiremockClient(
    new Host('localhost'),
    new Port(8086)
);

```

--------------------------------

### PhiremockServerCommand class method signatures

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server.md

Shows the method signatures of the PhiremockServerCommand class, including the constructor and the configure and execute methods.

```php
public function __construct()                     // parent::__construct('run')
protected function configure(): void
protected function execute(InputInterface $input, OutputInterface $output): int   // returns 0
```

--------------------------------

### Locate converter by version

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Locator methods for selecting the correct converter implementation based on the expectation version. The first routes on the 'version' key in the array (V1, V2, or absent defaults to V1) and throws an exception for unsupported versions. The second routes on the expectation's version string and throws an exception for any other value.

```php
// src/Common/Utils/ArrayToExpectationConverterLocator.php:8
public function locate(array $expectationArray): ArrayToExpectationConverter
//  'version' => '1' -> V1; 'version' => '2' -> V2; absent -> V1; otherwise throws
//  \Exception('Unimplemented configuration version: %s')
```

```php
// src/Common/Utils/ExpectationToArrayConverterLocator.php:9
public function locate(Expectation $expectation): ExpectationToArrayConverter
//  routes on $expectation->getVersion()->asString(); throws \Exception for anything else
```

--------------------------------

### FileSystem getRealPath method

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Instance method that resolves a path, including non-existent tail segments, against the filesystem. Used by the server to resolve the expectations directory for logging via `Factory::createFileSystemService`.

```php
public function getRealPath(string $path): string   // resolves non-existent tails against the filesystem
```

--------------------------------

### Mcustiel\Phiremock\Factory::createV1UtilsFactory

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Creates a factory for v1 dialect utilities, returning a Common\Utils\V1\Factory instance.

```APIDOC
## Factory Method: createV1UtilsFactory

### Description
Creates a factory for v1 dialect utilities, returning a Common\Utils\V1\Factory instance.

### Method
Factory Method

### Endpoint
`Mcustiel\Phiremock\Factory::createV1UtilsFactory`

### Parameters
None

### Return Value
- **Common\Utils\V1\Factory** - A factory instance for v1 utilities.

### Usage Example
```php
$factory = new Mcustiel\Phiremock\Factory();
$v1Factory = $factory->createV1UtilsFactory();
```
```

--------------------------------

### Composer require-dev dependency for Phiremock

Source: https://github.com/mcustiel/phiremock/blob/master/README.md

Add these dependencies to your composer.json under require-dev to install Phiremock v2.0 and Guzzle HTTP client ^6.0.

```json
    "require-dev": {
        "mcustiel/phiremock": "v2.0",
        "guzzlehttp/guzzle": "^6.0"
    }
```

--------------------------------

### Mcustiel\Phiremock\Factory::createV2UtilsFactory

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Creates a factory for v2 dialect utilities, returning a Common\Utils\V2\Factory instance.

```APIDOC
## Factory Method: createV2UtilsFactory

### Description
Creates a factory for v2 dialect utilities, returning a Common\Utils\V2\Factory instance.

### Method
Factory Method

### Endpoint
`Mcustiel\Phiremock\Factory::createV2UtilsFactory`

### Parameters
None

### Return Value
- **Common\Utils\V2\Factory** - A factory instance for v2 utilities.

### Usage Example
```php
$factory = new Mcustiel\Phiremock\Factory();
$v2Factory = $factory->createV2UtilsFactory();
```
```

--------------------------------

### ProxyResponse constructor and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-domain.md

Defines the ProxyResponse domain object. The constructor requires a Uri and accepts optional delay and new scenario state. __toString() returns 'proxy to: <uri>'. isProxyResponse() always returns true.

```php
public function __construct(Uri $uri, ?Delay $delayMillis = null, ?ScenarioState $newScenarioState = null)
public function __toString(): string               // 'proxy to: <uri>'
public function getUri(): Uri
public function isProxyResponse(): bool            // true
```

--------------------------------

### Count executions with countExecutions()

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Count received requests. Without arguments counts all requests; with a ConditionsBuilder it filters by conditions (here, GET requests to /api/users). Sends POST /__phiremock/executions and returns the count field from the JSON response.

```php
$total = $phiremock->countExecutions();
$getRequests = $phiremock->countExecutions(getRequest()->andUrl(isEqualTo('/api/users')));
```

--------------------------------

### Factory Methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-factory.md

Methods for creating Phiremock clients and remote connections.

```APIDOC
## Factory::createDefault()

### Description
Returns an instance of the client factory wired with a fresh `new PhiremockFactory()`.

### Method
`public static createDefault(): self`

### Parameters
None.

### Return Value
- `self` - A new `Factory` instance.

### Example
```php
$factory = Factory::createDefault();
```
```

```APIDOC
## Factory::createPhiremockClient(Host $host, Port $port, ?Scheme $scheme = null)

### Description
Builds a `Phiremock` client with v2 converters and a default PSR-18 remote connection.

### Method
`public createPhiremockClient(Host $host, Port $port, ?Scheme $scheme = null): Phiremock`

### Parameters
- `$host` (`Mcustiel\Phiremock\Client\Connection\Host`) - Required - Server host.
- `$port` (`Mcustiel\Phiremock\Client\Connection\Port`) - Required - Server port.
- `$scheme` (`?Mcustiel\Phiremock\Client\Connection\Scheme`) - Optional - Wire protocol. Defaults to `Scheme::createHttp()` when `null`.

### Return Value
- `Phiremock` - A configured Phiremock client.

### Example
```php
use Mcustiel\Phiremock\Client\Factory;
use Mcustiel\Phiremock\Client\Connection\Host;
use Mcustiel\Phiremock\Client\Connection\Port;

$client = Factory::createDefault()->createPhiremockClient(
    new Host('localhost'),
    new Port(8086)
);
```
```

```APIDOC
## Factory::createSecurePhiremockClient(Host $host, Port $port)

### Description
Builds a `Phiremock` client with the scheme forced to HTTPS.

### Method
`public createSecurePhiremockClient(Host $host, Port $port): Phiremock`

### Parameters
- `$host` (`Mcustiel\Phiremock\Client\Connection\Host`) - Required - Server host.
- `$port` (`Mcustiel\Phiremock\Client\Connection\Port`) - Required - Server port.

### Return Value
- `Phiremock` - A configured Phiremock client using HTTPS.

### Example
```php
$client = Factory::createDefault()->createSecurePhiremockClient(
    new Host('localhost'),
    new Port(8443)
);
```
```

```APIDOC
## Factory::createRemoteConnection()

### Description
Returns a PSR-18 HTTP client. Default implementation returns `new GuzzlePsr18Client()`. Override this method to provide a custom PSR-18 client.

### Method
`public createRemoteConnection(): ClientInterface`

### Parameters
None.

### Return Value
- `Psr\Http\Client\ClientInterface` - A PSR-18 compatible HTTP client.

### Throws
- `Exception` - If `\GuzzleHttp\Client` class is not available.

### Example
```php
namespace My\Namespace;

use GuzzleHttp\Client as GuzzleClient;
use Mcustiel\Phiremock\Client\Factory;
use Psr\Http\Client\ClientInterface;

class MyFactory extends Factory
{
    public function createRemoteConnection(): ClientInterface
    {
        return new GuzzleClient(); // e.g. Guzzle 7
    }
}
```
```

--------------------------------

### Run Phiremock server with custom factory and TLS

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/configuration.md

Run the Phiremock server with a custom factory class, TLS certificate options, and debug mode. The --factory-class flag points to the custom factory defined in the previous snippet.

```bash
./vendor/bin/phiremock \
    --ip 0.0.0.0 --port 8086 \
    --expectations-dir ./tests/expectations \
    --factory-class 'My\Namespace\MyFactory' \
    --certificate ./certs/server.pem --certificate-key ./certs/server.key --cert-passphrase secret \
    --debug
```

--------------------------------

### AddExpectationAction constructor

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server-actions.md

Constructor for adding expectations via POST /__phiremock/expectations. Maps request body via RequestToExpectationMapper::map(), validates, and adds to storage. Returns 201 on success or 500 on exception.

```php
public function __construct(
    RequestToExpectationMapper $converter,
    ExpectationStorage $storage,
    LoggerInterface $logger
)
```

--------------------------------

### HttpResponse constructor and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-domain.md

Defines the HttpResponse domain object. The constructor accepts optional status code, body, headers, delay in milliseconds, and new scenario state. Defaults to status code 200 when not provided. createEmpty() returns a response with status 200 and empty body. isHttpResponse() always returns true.

```php
public function __construct(
    ?StatusCode $statusCode = null,
    ?Body $body = null,
    ?HeadersCollection $headers = null,
    ?Delay $delayMillis = null,
    ?ScenarioState $newScenarioState = null
)
// defaults: statusCode ?? StatusCode::createDefault() (200)

public static function createEmpty(): self          // StatusCode(200) + Body('')
public function getStatusCode(): StatusCode
public function hasBody(): bool
public function getBody(): ?Body
public function hasHeaders(): bool
public function getHeaders(): ?HeadersCollection
public function isHttpResponse(): bool             // true
```

--------------------------------

### GuzzlePsr18Client::__construct

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-factory.md

Creates a new Guzzle PSR-18 client adapter. Accepts an optional Guzzle client instance, defaulting to a client with specific options for testing.

```APIDOC
## GuzzlePsr18Client::__construct

### Description
Creates a new Guzzle PSR-18 client adapter. Accepts an optional Guzzle client instance, defaulting to a client with specific options for testing.

### Method
Constructor

### Signature
```php
public function __construct(?GuzzleClient $client = null)
```

### Parameters
- `$client` (?GuzzleHttp\Client) - Optional - Guzzle instance. Default: `new GuzzleClient(['http_errors' => false, 'allow_redirects' => true, 'verify' => false])`

### Default Options
- `http_errors=false` - Status codes are returned, not thrown.
- `allow_redirects=true` - Redirects are followed.
- `verify=false` - TLS verification disabled for testing.
```

--------------------------------

### ResponseBuilder abstract methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Declares the methods for scenario transition, latency, and building a response. andDelayInMillis validates via Delay (int ≥ 0).

```php
public function andSetScenarioStateTo(string $scenarioState): ResponseBuilder
public function andDelayInMillis(int $delay): ResponseBuilder
public function build(): Response    // returns the base Mcustiel\Phiremock\Domain\Response
```

--------------------------------

### createExpectationFromJson(string $body): void

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Sends a raw JSON expectation configuration string to the mock server. The body is sent verbatim with Content-Type application/json, expecting HTTP 201 on success.

```APIDOC
## createExpectationFromJson(string $body): void

### Description
Installs an expectation using a raw JSON string (v1 or v2 dialect). The string is sent as the request body with Content-Type: application/json.

### Method
POST

### Endpoint
/__phiremock/expectations

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `$body` (string) - Required - Raw JSON expectation configuration (v1 or v2 dialect).

### Request Example
```php
$phiremock->createExpectationFromJson(
    '{"version": "2", "on": {"method": {"isSameString": "GET"}}, "then": {"response": {"statusCode": 204}}}'
);
```

### Response
#### Success Response (201)
- No response body documented.

#### Response Example
None documented.

### Error Handling
- **Psr\Http\Client\ClientExceptionInterface** - On transport failure.
- **RuntimeException** - If the server responds with a status other than `201` (same mapping as `createExpectation`).
```

--------------------------------

### ScenarioStateInfo constructor and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-domain.md

Defines the ScenarioStateInfo value object, a (name, state) pair used by ScenarioStorage::setScenarioState() and the scenarios admin endpoint.

```php
public function __construct(ScenarioName $name, ScenarioState $state)
public function getScenarioName(): ScenarioName
public function getScenarioState(): ScenarioState
```

--------------------------------

### ProxyResponseStrategy constructor

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server-utils.md

Constructor for ProxyResponseStrategy. It requires a scenario storage, a logger, and an HTTP client to forward requests to the proxy target.

```php
public function __construct(ScenarioStorage $scenarioStorage, LoggerInterface $logger, ClientInterface $httpService)
```

--------------------------------

### ConditionsBuilder public methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Public API of ConditionsBuilder. All and* methods return self for fluent chaining. build() returns a ConditionsBuilderResult wrapping a Mcustiel\Phiremock\Domain\Conditions.

```php
public function __construct(?MethodCondition $methodCondition = null, ?UrlCondition $urlCondition = null)
public static function create(?string $method = null, ?string $url = null): self
public function andMethod(Matcher $matcher): self
public function andBody(Matcher $matcher): self
public function andBinaryBody(Matcher $matcher): self
public function andHeader(string $header, Matcher $matcher): self
public function andFormField(string $fieldName, Matcher $matcher): self
public function andUrl(Matcher $matcher): self
public function andScenarioState(string $scenario, string $scenarioState): self
public function andJsonPath(string $path, Matcher $matcher): self
public function build(): ConditionsBuilderResult
```

--------------------------------

### Url::__construct

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-http.md

Creates a Url instance from a string. The string must match the URL path pattern, otherwise an InvalidArgumentException is thrown.

```APIDOC
## Url::__construct

### Description
Creates a Url instance from a string. The string must match the URL path pattern, otherwise an InvalidArgumentException is thrown.

### Method
__construct

### Signature
public function __construct(string $url)

### Parameters
- **url** (string) - Required - The URL string to validate and store. Must start with `/` and optionally include query/fragment.

### Throws
- **InvalidArgumentException** - If the URL does not match the pattern. Message: `Invalid http url: %s`

### Example
```php
$url = new Url('/path?query=1');
```
```

--------------------------------

### Phiremock Factory Methods for Creating Utils Factories and Locators

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Methods to create v1/v2 utils factories and converter locators. Used internally by client and server factories to select the dialect.

```php
public function createV1UtilsFactory(): FactoryV1                                // Common\Utils\V1\Factory
public function createV2UtilsFactory(): FactoryV2                                // Common\Utils\V2\Factory
public function createExpectationToArrayConverterLocator(): ExpectationToArrayConverterLocator
public function createArrayToExpectationConverterLocator(): ArrayToExpectationConverterLocator
```

--------------------------------

### Uri::asString

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-http.md

Returns the URI as a string.

```APIDOC
## Uri::asString

### Description
Returns the URI as a string.

### Method
asString

### Signature
public function asString(): string

### Returns
- **string** - The URI string.

### Example
```php
$uri = new Uri('https://example.com');
echo $uri->asString(); // https://example.com
```
```

--------------------------------

### Create Phiremock client with default scheme

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-factory.md

Creates a Phiremock client with default HTTP scheme using the factory's createPhiremockClient method.

```php
use Mcustiel\Phiremock\Client\Factory;
use Mcustiel\Phiremock\Client\Connection\Host;
use Mcustiel\Phiremock\Client\Connection\Port;

$client = Factory::createDefault()->createPhiremockClient(
    new Host('localhost'),
    new Port(8086)
);

```

--------------------------------

### resetScenarios(): void

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Resets all scenarios to their initial state.

```APIDOC
## resetScenarios(): void

### Description
Resets all scenarios to their initial state (Scenario.START). Uses DELETE /__phiremock/scenarios and expects a 200 response.

### Method
DELETE

### Endpoint
/__phiremock/scenarios

### Response
#### Success Response (200)
No content.
```

--------------------------------

### createExpectation(Expectation $expectation): void

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Serializes an Expectation object and POSTs it to /__phiremock/expectations. Expects HTTP 201 on success. Throws exceptions on encoding or transport failure, or if the server returns a non-201 status.

```APIDOC
## createExpectation(Expectation $expectation): void

### Description
Installs an expectation on the mock server. The expectation is serialized according to the client's converter dialect (default v2) and sent via HTTP POST.

### Method
POST

### Endpoint
/__phiremock/expectations

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `$expectation` (Mcustiel\Phiremock\Domain\Expectation) - Required - The expectation to install on the server.

### Request Example
```php
use Mcustiel\Phiremock\Client\Phiremock;
use Mcustiel\Phiremock\Client\Utils\A;
use Mcustiel\Phiremock\Client\Utils\Is;
use Mcustiel\Phiremock\Client\Utils\Respond;

$phiremock->createExpectation(
    Phiremock::on(A::getRequest()->andUrl(Is::equalTo('/potato')))
        ->then(Respond::withStatusCode(200)->andBody('stub body'))
);
```

### Response
#### Success Response (201)
- No response body documented.

#### Response Example
None documented.

### Error Handling
- **RuntimeException** - If `json_encode` fails ("Error generating json body for request: …").
- **Psr\Http\Client\ClientExceptionInterface** - On transport failure.
- **RuntimeException** - If the server responds with a status other than `201` (see the error-mapping table under "Response validation").
```

--------------------------------

### BinaryBody class methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-http.md

Extends Body and overrides asString() to return a base64-encoded string with the 'phiremock.base64:' prefix, and isTextBody() to return false. The prefix travels through the JSON wire format and is decoded by BodyHelper.

```php
public function asString(): string    // 'phiremock.base64:' . base64_encode(original)
public function isTextBody(): bool    // false
```

--------------------------------

### ConditionsBuilderResult constructor and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Shows the constructor and getter methods of ConditionsBuilderResult. The constructor takes RequestConditions and an optional ScenarioName. getRequestConditions returns RequestConditions, getScenarioName returns ?ScenarioName.

```php
public function __construct(RequestConditions $request, ?ScenarioName $scenarioName = null)
public function getRequestConditions(): RequestConditions        // Mcustiel\Phiremock\Domain\Conditions
public function getScenarioName(): ?ScenarioName                 // Mcustiel\Phiremock\Domain\Options\ScenarioName
```

--------------------------------

### Common\UtilsFactory::createArrayToScenarioStateInfoConverter

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Creates an array-to-scenario-state-info converter instance.

```APIDOC
## Interface Method: createArrayToScenarioStateInfoConverter

### Description
Creates an array-to-scenario-state-info converter instance.

### Method
Interface Method

### Endpoint
`Mcustiel\Phiremock\Common\UtilsFactory::createArrayToScenarioStateInfoConverter`

### Parameters
None

### Return Value
- **ArrayToScenarioStateInfoConverter** - A converter instance.

### Usage Example
```php
$factory = new V1\Factory(); // or V2\Factory
$converter = $factory->createArrayToScenarioStateInfoConverter();
```
```

--------------------------------

### Version class constants and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-domain.md

Defines the valid versions '1' and '2' and the constructor and asString method. Throws InvalidArgumentException with message 'Invalid version: %s' for any other value.

```php
private const VALID_VERSIONS = ['1', '2'];
public function __construct(string $version)
public function asString(): string
```

--------------------------------

### createExpectation with fluent API

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-facade.md

Creates an expectation using the fluent API. The expectation is serialized and POSTed to /__phiremock/expectations, expecting HTTP 201. Throws RuntimeException if json_encode fails or if the server responds with a status other than 201.

```php
use Mcustiel\Phiremock\Client\Phiremock;
use Mcustiel\Phiremock\Client\Utils\A;
use Mcustiel\Phiremock\Client\Utils\Is;
use Mcustiel\Phiremock\Client\Utils\Respond;

$phiremock->createExpectation(
    Phiremock::on(A::getRequest()->andUrl(Is::equalTo('/potato')))
        ->then(Respond::withStatusCode(200)->andBody('stub body'))
);
```

--------------------------------

### ConditionsBuilder::__construct

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Constructs a ConditionsBuilder instance with optional initial method and URL conditions.

```APIDOC
## ConditionsBuilder::__construct

### Description
Creates a new ConditionsBuilder instance, optionally initializing it with a method condition and a URL condition.

### Method
`public function __construct(?MethodCondition $methodCondition = null, ?UrlCondition $urlCondition = null)`

### Parameters
- `$methodCondition` (MethodCondition|null) - Optional - The initial method condition.
- `$urlCondition` (UrlCondition|null) - Optional - The initial URL condition.

### Returns
`self` (fluent)

### Notes
Both parameters are optional.

```

--------------------------------

### Url::asString

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-http.md

Returns the URL as a string.

```APIDOC
## Url::asString

### Description
Returns the URL as a string.

### Method
asString

### Signature
public function asString(): string

### Returns
- **string** - The URL string.

### Example
```php
$url = new Url('/path?query=1');
echo $url->asString(); // /path?query=1
```
```

--------------------------------

### Common\UtilsFactory::createProxyResponseToArrayConverter

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Creates a proxy-response-to-array converter instance.

```APIDOC
## Interface Method: createProxyResponseToArrayConverter

### Description
Creates a proxy-response-to-array converter instance.

### Method
Interface Method

### Endpoint
`Mcustiel\Phiremock\Common\UtilsFactory::createProxyResponseToArrayConverter`

### Parameters
None

### Return Value
- **ResponseToArrayConverter** - A converter instance.

### Usage Example
```php
$factory = new V1\Factory(); // or V2\Factory
$converter = $factory->createProxyResponseToArrayConverter();
```
```

--------------------------------

### ExpectationBuilder constructor and methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Shows the constructor and methods of ExpectationBuilder. The constructor takes a ConditionsBuilder. then() builds a response via ResponseBuilder, thenRespond is shorthand for HttpResponseBuilder::create($status)->andBody($body)->build(). Both produce an Expectation with Version '2'.

```php
public function __construct(ConditionsBuilder $requestBuilder)
public function then(ResponseBuilder $responseBuilder): Expectation
public function thenRespond(int $statusCode, string $body): Expectation
```

--------------------------------

### ListExpectationsAction constructor

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server-actions.md

Constructor for ListExpectationsAction. Injects the expectation storage and the converter locator used to serialize expectations to arrays.

```php
public function __construct(
    ExpectationStorage $storage,
    ExpectationToArrayConverterLocator $converterLocator
)
```

--------------------------------

### FileExpectationsLoader public methods

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-server-utils.md

Public API of the FileExpectationsLoader class. The constructor receives a converter locator, active storage, backup storage, and a logger. The load methods throw Exception on invalid JSON or validation failure.

```php
public function __construct(
    ArrayToExpectationConverterLocator $converterLocator,
    ExpectationStorage $storage,
    ExpectationStorage $backup,
    LoggerInterface $logger
)
```

```php
/** @throws Exception */
public function loadExpectationFromFile(string $fileName): void
```

```php
/** @throws Exception */
public function loadExpectationsFromDirectory(string $directory): void
```

--------------------------------

### Common\UtilsFactory::createScenarioStateInfoToArrayConverter

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-common-utils.md

Creates a scenario-state-info-to-array converter instance.

```APIDOC
## Interface Method: createScenarioStateInfoToArrayConverter

### Description
Creates a scenario-state-info-to-array converter instance.

### Method
Interface Method

### Endpoint
`Mcustiel\Phiremock\Common\UtilsFactory::createScenarioStateInfoToArrayConverter`

### Parameters
None

### Return Value
- **ScenarioStateInfoToArrayConverter** - A converter instance.

### Usage Example
```php
$factory = new V1\Factory(); // or V2\Factory
$converter = $factory->createScenarioStateInfoToArrayConverter();
```
```

--------------------------------

### ConditionsBuilder::create

Source: https://github.com/mcustiel/phiremock/blob/master/_autodocs/api-reference/phiremock-client-builders.md

Static factory method that creates a ConditionsBuilder from an optional HTTP method and URL string.

```APIDOC
## ConditionsBuilder::create

### Description
Creates a new ConditionsBuilder instance from a method string and a URL string. The method is wrapped in a `MethodCondition` using `MatcherFactory::sameString`, and the URL is wrapped in `UrlCondition` using `MatcherFactory::equalsTo`.

### Method
`public static function create(?string $method = null, ?string $url = null): self`

### Parameters
- `$method` (string|null) - Optional - The HTTP method.
- `$url` (string|null) - Optional - The URL.

### Returns
`self`

### Example
```php
use Mcustiel\Phiremock\Client\Utils\ConditionsBuilder;

$builder = ConditionsBuilder::create('POST', '/users');
```

```
Tokens:
Raw