Drupal Test Helpers module API documentation - release 1.5.0

HttpClientFactoryStub extends ClientFactory
in package

Helper class to construct a HTTP client for capturing and mocking responses.

It allows to grab the responses from the real requests and store them to the files in the 'store' mode.

And in the 'mock' mode - read the responses from files without making real HTTP requests.

Tags
see

tests/src/Unit/Stub/HttpClientFactoryStubTest.php for the usage examples.

Table of Contents

Constants

EMV_HTTP_CLIENT_MODE  = 'TH_HTTP_CLIENT_MODE'
The environment variable to control the HTTP client mode - store or mock.
HANDLER_NAME_AFTER_REAL_CALL  = 'test_helpers_http_client_mock.handler_after_real_call'
HANDLER_NAME_BEFORE_REAL_CALL  = 'test_helpers_http_client_mock.handler_before_real_call'
HANDLER_NAME_CUSTOM  = 'test_helpers_http_client_mock.handler_custom'
The HTTP handler names to find them in the stack.
HANDLER_NAME_CUSTOM_RESPONSES_STACK  = 'test_helpers_http_client_mock.handler_custom_responses_stack'
HTTP_CLIENT_MODE_APPEND  = 'append'
The mode to store requests responses only if the stored one is missing.
HTTP_CLIENT_MODE_MOCK  = 'mock'
The mode to mock all outgoing requests responses from files.
HTTP_CLIENT_MODE_STORE  = 'store'
The mode to store all outgoing requests responses to files.
OPTION_CONTEXT  = 'context'
OPTION_LOG_STORED_RESPONSES_USAGE_FILE  = 'log_stored_responses_usage_file'
OPTION_STORE_HEADERS  = 'store_headers'
The options keys.
OPTION_STORE_HEADERS_SKIP_KEYS  = 'store_headers_skip'
OPTION_URI_REGEXP  = 'uri_regexp'

Properties

$handledRequests  : array<string|int, mixed>
A storage for used (stored and mocked) responses by the usage order.
$options  : array<string|int, mixed>|null
$requestMockMode  : string|null
$responsesStorageDirectory  : string|null
$stubContext  : string|null
The context for the stub that is used to generate the stored assets hash.
$stubCustomResponsesStack  : array<string|int, Response>
A stack with custom responses.
$stubHandlerCustom  : callable|null
A custom handler for HTTP requests.
$stubHandlerStackLast  : HandlerStack|null
The handler stack, attached to the last created HTTP client.
$testName  : string|null

Methods

__construct()  : mixed
HttpClientFactoryStub constructor.
fromOptions()  : mixed
{@inheritdoc}
stubAddCustomResponseToStack()  : mixed
Adds a custom response to the stack.
stubDeleteStoredResponseByHash()  : void
Deletes the stored response files from the storage by the request hash.
stubGetContext()  : string|null
Gets the current context value used in generating responses hash.
stubGetHandledRequests()  : array<string|int, mixed>
Returns the list of hashes of all mocked responses.
stubGetLastResponse()  : string
Returns the last request response body.
stubGetRequestFilename()  : string
Gets the request filename by the hash.
stubGetRequestFilenameFromRequest()  : string
Gets the stored response filename from a Request.
stubGetRequestHash()  : string
Generates a hash for a request.
stubGetRequestMockMode()  : string|null
Returns the current HTTP Requests mocking mode: none, store, mock.
stubGetResponsesStorageDirectory()  : string
Returns the current responses storage directory.
stubGetResponseUsageLog()  : array<string|int, mixed>
Retrieves the response usage log entries from the log file as array.
stubGetStoredResponse()  : Response
Gets the stored response of a request from the storage.
stubGetStoredResponseByHash()  : Response
Get the stored response from the storage by the request hash.
stubGetStoredResponseMetadataByHash()  : array<string|int, mixed>
Get the stored response metadata from the storage by the request hash.
stubGetTestName()  : string
Gets the current test name, or generates it if not set.
stubGetUriRegexp()  : string|null
Gets the URI regular expression.
stubHasStoredResponse()  : bool
Checks if a stored response exists for the given request.
stubRemoveResponseUsageLog()  : void
Removes the response usage log file.
stubSetContext()  : void
Sets the context value to use for generating the stored responses hash.
stubSetCustomHandler()  : mixed
Sets a custom handler for the HTTP client.
stubSetRequestMockMode()  : void
Sets the HTTP Requests mocking mode.
stubSetResponsesStorageDirectory()  : void
Sets the current responses storage directory.
stubSetStoredResponseMetadataByHash()  : void
Stores the stored response metadata by the request hash.
stubSetTestName()  : void
Sets the test name, autodetect the name if not provided.
stubSetUriRegexp()  : void
Sets the URI regular expression.
stubStoreResponse()  : mixed
Stores the response for a request to the storage.
ensureTestNameInMetadata()  : bool
Ensures that the test name is present in the metadata.
prepareMetadata()  : array<string|int, mixed>
Prepares the metadata array.
stubGetRequestMetadata()  : array<string|int, string>
Generates a hash for a request.
stubIsPhpunitTest()  : bool
Checks if the current test using PHPUnit.
stubMatchRequest()  : bool
Matches a request against the URI regular expression.
stubStoreRequestHashUsage()  : void
Adds the request hash to the container.
stubLogResponseUsage()  : void
Logs the response usage to the log file.

Constants

EMV_HTTP_CLIENT_MODE

The environment variable to control the HTTP client mode - store or mock.

public string EMV_HTTP_CLIENT_MODE = 'TH_HTTP_CLIENT_MODE'

HANDLER_NAME_AFTER_REAL_CALL

public mixed HANDLER_NAME_AFTER_REAL_CALL = 'test_helpers_http_client_mock.handler_after_real_call'

HANDLER_NAME_BEFORE_REAL_CALL

public mixed HANDLER_NAME_BEFORE_REAL_CALL = 'test_helpers_http_client_mock.handler_before_real_call'

HANDLER_NAME_CUSTOM

The HTTP handler names to find them in the stack.

public string HANDLER_NAME_CUSTOM = 'test_helpers_http_client_mock.handler_custom'

HANDLER_NAME_CUSTOM_RESPONSES_STACK

public mixed HANDLER_NAME_CUSTOM_RESPONSES_STACK = 'test_helpers_http_client_mock.handler_custom_responses_stack'

HTTP_CLIENT_MODE_APPEND

The mode to store requests responses only if the stored one is missing.

public string HTTP_CLIENT_MODE_APPEND = 'append'

HTTP_CLIENT_MODE_MOCK

The mode to mock all outgoing requests responses from files.

public string HTTP_CLIENT_MODE_MOCK = 'mock'

HTTP_CLIENT_MODE_STORE

The mode to store all outgoing requests responses to files.

public string HTTP_CLIENT_MODE_STORE = 'store'

OPTION_LOG_STORED_RESPONSES_USAGE_FILE

public mixed OPTION_LOG_STORED_RESPONSES_USAGE_FILE = 'log_stored_responses_usage_file'

OPTION_STORE_HEADERS_SKIP_KEYS

public mixed OPTION_STORE_HEADERS_SKIP_KEYS = 'store_headers_skip'

Properties

$handledRequests

A storage for used (stored and mocked) responses by the usage order.

protected array<string|int, mixed> $handledRequests = []

$stubContext

The context for the stub that is used to generate the stored assets hash.

protected string|null $stubContext = NULL

$stubCustomResponsesStack

A stack with custom responses.

protected array<string|int, Response> $stubCustomResponsesStack = []

$stubHandlerCustom

A custom handler for HTTP requests.

protected callable|null $stubHandlerCustom = NULL

$stubHandlerStackLast

The handler stack, attached to the last created HTTP client.

protected HandlerStack|null $stubHandlerStackLast = NULL

Used to dynamically control the custom handler.

Methods

__construct()

HttpClientFactoryStub constructor.

public __construct([HandlerStack|null $stack = NULL ][, string|null $requestMockMode = NULL ][, string|null $responsesStorageDirectory = NULL ][, string|null $testName = NULL ][, string|null $options = NULL ]) : mixed
Parameters
$stack : HandlerStack|null = NULL

The HTTP client stack.

$requestMockMode : string|null = NULL

The requests mocking mode: NULL, 'store', 'mock', 'append'.

  • append: makes a new request only if the stored response is missing.
$responsesStorageDirectory : string|null = NULL

The directory to store responses.

$testName : string|null = NULL

The name of the test.

$options : string|null = NULL

An associative array of options. Supported keys:

  • store_headers: (bool) Store headers of the response. Defaults to FALSE.
  • skip_headers: (array) A list of headers to not store. Defaults to [].
  • uri_regexp: (string) A regular expression for the URI to store. Defaults to ''.

fromOptions()

{@inheritdoc}

public fromOptions([array<string|int, mixed> $config = [] ]) : mixed
Parameters
$config : array<string|int, mixed> = []

stubAddCustomResponseToStack()

Adds a custom response to the stack.

public stubAddCustomResponseToStack(ResponseInterface $response) : mixed
Parameters
$response : ResponseInterface

A response to add.

stubDeleteStoredResponseByHash()

Deletes the stored response files from the storage by the request hash.

public stubDeleteStoredResponseByHash(string $hash) : void
Parameters
$hash : string

A request hash.

stubGetContext()

Gets the current context value used in generating responses hash.

public stubGetContext() : string|null
Return values
string|null —

The context value.

stubGetHandledRequests()

Returns the list of hashes of all mocked responses.

public stubGetHandledRequests() : array<string|int, mixed>
Return values
array<string|int, mixed> —

A list of hashes of all mocked responses.

stubGetLastResponse()

Returns the last request response body.

public stubGetLastResponse([int $delta = 0 ]) : string
Parameters
$delta : int = 0
Return values
string —

The last response body.

stubGetRequestFilename()

Gets the request filename by the hash.

public stubGetRequestFilename(string $hash[, bool $metadata = FALSE ]) : string
Parameters
$hash : string

A hash.

$metadata : bool = FALSE

A flag to return the metadata file instead.

Return values
string —

A full path to the file.

stubGetRequestFilenameFromRequest()

Gets the stored response filename from a Request.

public stubGetRequestFilenameFromRequest(Request $request[, bool $metadata = FALSE ]) : string
Parameters
$request : Request

A request.

$metadata : bool = FALSE

A flag to return the metadata filename.

Return values
string —

A full path to the stored response file.

stubGetRequestHash()

Generates a hash for a request.

public stubGetRequestHash(Request $request) : string
Parameters
$request : Request

A request.

Return values
string —

The generated hash.

stubGetRequestMockMode()

Returns the current HTTP Requests mocking mode: none, store, mock.

public stubGetRequestMockMode() : string|null

If the mode is not set explicitly, it is controllable by the TH_HTTP_CLIENT_MODE environment variable:

  • TH_HTTP_CLIENT_MODE=store enables real requests and store them.
  • TH_HTTP_CLIENT_MODE=mock mock all requests from the storage.
Return values
string|null —

The current mode:

  • NULL - works as default Drupal http_client
  • store - stores all response to the storage.
  • mock - mocks all requests from the storage.

stubGetResponsesStorageDirectory()

Returns the current responses storage directory.

public stubGetResponsesStorageDirectory() : string
Return values
string

stubGetResponseUsageLog()

Retrieves the response usage log entries from the log file as array.

public stubGetResponseUsageLog() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The array of log entries.

stubGetStoredResponse()

Gets the stored response of a request from the storage.

public stubGetStoredResponse(Request $request) : Response
Parameters
$request : Request

A request.

Tags
throws
Exception

When there is no stored response found.

Return values
Response —

The stored response.

stubGetStoredResponseByHash()

Get the stored response from the storage by the request hash.

public stubGetStoredResponseByHash(string $hash) : Response
Parameters
$hash : string

A request hash.

Return values
Response —

The stored response.

stubGetStoredResponseMetadataByHash()

Get the stored response metadata from the storage by the request hash.

public stubGetStoredResponseMetadataByHash(string $hash) : array<string|int, mixed>
Parameters
$hash : string

A request hash.

Return values
array<string|int, mixed> —

The stored response metadata array.

stubGetTestName()

Gets the current test name, or generates it if not set.

public stubGetTestName() : string
Return values
string —

The current test name.

stubGetUriRegexp()

Gets the URI regular expression.

public stubGetUriRegexp() : string|null
Return values
string|null —

The URI regular expression.

stubHasStoredResponse()

Checks if a stored response exists for the given request.

public stubHasStoredResponse(Request $request) : bool
Parameters
$request : Request

The request object to check for a stored response.

Return values
bool —

TRUE if a stored response exists, FALSE otherwise.

stubRemoveResponseUsageLog()

Removes the response usage log file.

public stubRemoveResponseUsageLog() : void

stubSetContext()

Sets the context value to use for generating the stored responses hash.

public stubSetContext([string|null $context = NULL ]) : void
Parameters
$context : string|null = NULL

The context value. Use NULL to reset the context.

stubSetCustomHandler()

Sets a custom handler for the HTTP client.

public stubSetCustomHandler(callable|null $handler) : mixed
Parameters
$handler : callable|null

A custom handler or null to unset the handler.

stubSetRequestMockMode()

Sets the HTTP Requests mocking mode.

public stubSetRequestMockMode(mixed $mode) : void
Parameters
$mode : mixed

A mode: store, mock, append or NULL to use the Drupal default mode.

stubSetResponsesStorageDirectory()

Sets the current responses storage directory.

public stubSetResponsesStorageDirectory(string $directory) : void
Parameters
$directory : string

stubSetStoredResponseMetadataByHash()

Stores the stored response metadata by the request hash.

public stubSetStoredResponseMetadataByHash(array<string|int, mixed> $metadata, string $hash) : void
Parameters
$metadata : array<string|int, mixed>

The metadata to set.

$hash : string

A request hash.

stubSetTestName()

Sets the test name, autodetect the name if not provided.

public stubSetTestName([string|null $name = NULL ]) : void
Parameters
$name : string|null = NULL

The test name. If NULL - tries to autodetect it.

stubSetUriRegexp()

Sets the URI regular expression.

public stubSetUriRegexp(string|null $regexp) : void
Parameters
$regexp : string|null

The URI regular expression.

stubStoreResponse()

Stores the response for a request to the storage.

public stubStoreResponse(Response $response[, Request $request = NULL ][, string|null $hash = NULL ]) : mixed
Parameters
$response : Response

The response to store.

$request : Request = NULL

The request, is used to generate the hash.

$hash : string|null = NULL

The custom hash value to use when storing. Useful when you need to store a modified response.

ensureTestNameInMetadata()

Ensures that the test name is present in the metadata.

protected ensureTestNameInMetadata(array<string|int, mixed> &$metadata) : bool
Parameters
$metadata : array<string|int, mixed>

The metadata array to check.

Return values
bool —

TRUE if the test name is already present, FALSE otherwise.

prepareMetadata()

Prepares the metadata array.

protected prepareMetadata(Request|null $request, Response $response) : array<string|int, mixed>
Parameters
$request : Request|null

The request.

$response : Response

The response.

Return values
array<string|int, mixed>

stubGetRequestMetadata()

Generates a hash for a request.

protected stubGetRequestMetadata(Request $request) : array<string|int, string>
Parameters
$request : Request

A request.

Return values
array<string|int, string> —

An associative array with the request metadata:

  • method: The request method.
  • uri: The request URI.
  • body: The request body, if not empty.

stubIsPhpunitTest()

Checks if the current test using PHPUnit.

protected stubIsPhpunitTest() : bool
Return values
bool —

True if PHPUnit, false otherwise.

stubMatchRequest()

Matches a request against the URI regular expression.

protected stubMatchRequest(Request $request) : bool
Parameters
$request : Request

The request to match.

Return values
bool —

TRUE if the request matches the URI regular expression, FALSE otherwise.

stubStoreRequestHashUsage()

Adds the request hash to the container.

protected stubStoreRequestHashUsage(string $hash) : void
Parameters
$hash : string

A hash value.

stubLogResponseUsage()

Logs the response usage to the log file.

private stubLogResponseUsage(string $hash, string $operation) : void
Parameters
$hash : string

A hash of the request.

$operation : string

The operation type: 'read', 'create', 'update', 'check', 'missing'.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results