PendingRequest
class PendingRequest implements Transient
Traits
Constants
| DATA_OPTION |
|
| PRIOR_SENDS_OPTION |
|
| DESTINATION_POLICY_OPTION |
|
| TRACE_OPTION |
|
| TRACE_PROPAGATION_OPTION |
|
| DEFAULT_DESTINATION_RESOLUTION_TIMEOUT |
|
| protected PREPARED_BODY_OPTION |
|
| protected STUB_SINK_CHUNK_SIZE |
The largest faked body write to a sink, matching cURL's default maximum write size. |
Properties
| static protected array | $macros | The registered string macros. |
from Macroable |
| protected ClientInterface|null | $client | The Guzzle client instance. |
|
| protected callable | $handler | The Guzzle HTTP handler. |
|
| protected string | $baseUrl | The base URL for the request. |
|
| protected array | $urlParameters | The parameters that can be substituted into the URL. |
|
| protected string | $bodyFormat | The request body format. |
|
| protected null|resource|StreamInterface|string | $pendingBody | The raw body for the request. |
|
| protected array | $pendingFiles | The pending files for the request. |
|
| protected StreamInterface> | $multipartStreams | The streams wrapping attached multipart resources, keyed by resource ID. |
|
| protected CookieJar | $cookies | The request cookies. |
|
| protected TransferStats|null | $transferStats | The transfer stats for the request. |
|
| protected int | $sendCount | The number of physical requests started during the current logical send. |
|
| protected array | $options | The request options. |
|
| protected array | $baseOptions | The factory-level options applied below connection and request options. |
|
| protected Closure|null | $throwCallback | A callback to run when throwing if a server or client error occurs. |
|
| protected Closure|null | $throwIfCallback | A callback to check if an exception should be thrown when a server or client error occurs. |
|
| protected array<int, float|int>|int | $tries | The number of times to try the request. |
|
| protected Throwable): int|int | $retryDelay | The number of milliseconds to wait between retries. |
|
| protected bool | $retryThrow | Whether to throw an exception when all retries fail. |
|
| protected null|callable(null|Throwable, static, null|string): bool | $retryWhenCallback | The callback that will determine if the request should be retried. |
|
| protected Collection | $beforeSendingCallbacks | The callbacks that should execute before the request is sent. |
|
| protected Response, null|Request): mixed> | $afterResponseCallbacks | The callbacks that should execute after the response is built. |
|
| protected Collection|null | $stubCallbacks | The stub callables that will handle requests. |
|
| protected bool | $preventStrayRequests | Indicates that an exception should be thrown if any request is not faked. |
|
| protected array | $allowedStrayRequestUrls | The URL patterns that are allowed as stray requests. |
|
| protected Collection | $middleware | The middleware callables added by users that will handle requests. |
|
| protected TAsync | $async | Whether the requests should be asynchronous. |
|
| protected array | $attributes | The attributes to track with the request. |
|
| protected PromiseInterface|null | $promise | The pending request promise. |
|
| protected Request|null | $request | The sent request object, if a request has been made. |
|
| protected string|null | $connection | The current connection name for the pending request. |
|
| protected array|null | $connectionConfig | The current connection configuration for the pending request. |
|
| protected array | $mergeableOptions | The Guzzle request options whose entries accumulate across option layers. |
|
| protected false|int|null | $truncateExceptionsAt | The length at which request exceptions will be truncated. |
Methods
Apply the callback if the given "value" is (or resolves to) truthy.
Apply the callback if the given "value" is (or resolves to) falsy.
Mix another object into the class.
Dynamically handle calls to the class.
Dynamically handle calls to the class.
Create a new HTTP Client instance.
Set the base URL for the pending request.
Attach a raw body to the request.
Indicate the request contains JSON.
Indicate the request contains form parameters.
Attach a file to the request.
Indicate the request is a multi-part form request.
Specify the body format of the request.
Set the given query parameters in the request URI.
Specify the request's content type.
Indicate that JSON should be returned by the server.
Indicate the type of content that should be returned by the server.
Add the given headers to the request.
Add the given header to the request.
Replace the given headers on the request.
Specify the basic authentication username and password for the request.
Specify the digest authentication username and password for the request.
Specify an authorization token for the request.
Specify the user agent for the request.
Specify the URL parameters that can be substituted into the request URL.
Specify a cookie and its attributes for the request.
Specify the cookies that should be included with the request.
Specify the maximum number of redirects to allow.
Indicate that redirects should not be followed.
Indicate that TLS certificates should not be verified.
Restrict the request's destinations to those the given policy allows.
Resolve and pin a destination within this request's timeout limits.
Specify the path where the body of the response should be stored.
Specify the timeout (in seconds) for the request.
Specify the connect timeout (in seconds) for the request.
Replace the specified options on the request.
Add new middleware the client handler stack.
Prepend new middleware to the client handler stack.
Add new request middleware the client handler stack.
Add new response middleware the client handler stack.
Set arbitrary attributes to store with the request.
Get the attributes stored with the request.
Indicate that Telescope should not record this request.
Set Telescope tags for this request.
Indicate that OpenTelemetry should trace this request.
Indicate that OpenTelemetry should not trace this request.
Indicate that trace context should not be automatically added to this request.
Add a new "before sending" callback to the request.
Add a new callback to execute after the response is built.
Throw an exception if a server or client error occurs.
Throw an exception if a server or client error occurred and the given condition evaluates to true.
Throw an exception if a server or client error occurred and the given condition evaluates to false.
Dump the request before sending.
Dump the request before sending and end the script.
Issue a GET request to the given URL.
Issue a HEAD request to the given URL.
Issue a QUERY request to the given URL.
Issue a POST request to the given URL.
Issue a PATCH request to the given URL.
Issue a DELETE request to the given URL.
Send the request to the given URL.
Substitute the URL parameters in the given URL.
Parse the given HTTP options and set the appropriate additional options.
Parse multi-part form data.
Wrap the multipart stream resources in PSR-7 streams so they are not closed between retry attempts.
Rewind the seekable multipart streams so each attempt contains the full part contents.
Send an asynchronous request to the given URL.
Handle the response of an asynchronous request.
Get the maximum number of attempts for the request.
Get the delay in milliseconds before the next retry attempt.
Send a request either synchronously or asynchronously.
Get the request data as an array so that we can attach it to the request for convenient assertions.
Normalize the given request options.
Normalize the given header values.
Normalize the given header value.
Normalize non-finite floats within a nested array.
Normalize the given multipart option.
Normalize the given multipart headers.
Normalize the given request option value.
Normalize a query supplied to a GET request.
Normalize nested structured data values.
Normalize a scalar to a string without triggering PHP 8.5 non-finite float warnings.
Ensure the given request body can be passed to Guzzle.
Build the Guzzle client.
Create a new Guzzle client.
Build the Guzzle client handler stack.
Create a request-owned transport for destination pinning.
Add the necessary handlers to the given handler stack.
Build the prepared body tracking handler.
Build the before sending handler.
Build the recorder handler.
Build the stub handler.
Get the sink stub handler callback.
Return idle database sessions before waiting for an external service.
Build the destination policy handler.
Send one physical request to the addresses the destination policy vetted.
Execute the "before sending" callbacks.
Replace the given options with the current request options.
Create a new response instance using the given PSR response.
Register a stub callable that will intercept requests and be able to return stub responses.
Indicate that an exception should be thrown if any request is not faked.
Allow stray, unfaked requests for specific URL patterns.
Determine if the given URL is allowed as a stray request.
Toggle asynchronicity in requests.
Retrieve the pending request promise.
Dispatch the RequestSending event if a dispatcher is available.
Dispatch the ResponseReceived event if a dispatcher is available.
Dispatch the ConnectionFailed event if a dispatcher is available.
Indicate that request exceptions should be truncated to the given length.
Indicate that request exceptions should not be truncated.
Handle the given transport exception.
Handle the given transport exception that carried a response.
Preserve an asynchronous transfer failure even when its response status is successful.
Set the client instance.
Create a new client instance using the given handler.
Get the pending request options.
Set the pending request connection.
Get the pending request connection.
Get the pending request connection configuration.
Get the effective request-option preset for the selected connection.
Merge HTTP option layers using the request-option merge rules.
Merge an option value from a later layer over the current value.
Reject options whose ownership belongs to dedicated APIs.
Flush all static state.
Details
in
Conditionable at line 23
mixed
when(mixed $value = null, callable|null $callback = null, callable|null $default = null)
Apply the callback if the given "value" is (or resolves to) truthy.
in
Conditionable at line 56
mixed
unless(mixed $value = null, callable|null $callback = null, callable|null $default = null)
Apply the callback if the given "value" is (or resolves to) falsy.
in
Macroable at line 30
static void
macro(string $name, callable|object $macro)
Register a custom macro.
Macros persist in a static property for the worker lifetime and apply to every subsequent call on the macroable class.
in
Macroable at line 44
static void
mixin(object $mixin, bool $replace = true)
Mix another object into the class.
Delegates to macro() for each method; registered macros persist in a static property for the worker lifetime.
in
Macroable at line 61
static bool
hasMacro(string $name)
Check if macro is registered.
in
Macroable at line 72
static void
flushMacros()
Flush the existing macros.
Clears worker-wide macros; concurrent coroutines may resolve different methods depending on timing.
in
Macroable at line 83
static mixed
__callStatic(string $method, array $parameters)
Dynamically handle calls to the class.
in
Macroable at line 108
mixed
__call(string $method, array $parameters)
Dynamically handle calls to the class.
at line 274
__construct(Factory|null $factory = null, array $middleware = [], array $options = [])
Create a new HTTP Client instance.
at line 310
PendingRequest
baseUrl(string $url)
Set the base URL for the pending request.
at line 325
PendingRequest
withBody(mixed $content, string|null $contentType = 'application/json')
Attach a raw body to the request.
at line 347
PendingRequest
asJson()
Indicate the request contains JSON.
at line 357
PendingRequest
asForm()
Indicate the request contains form parameters.
at line 368
PendingRequest
attach(array|string $name, resource|string $contents = '', string|null $filename = null, array $headers = [])
Attach a file to the request.
at line 404
PendingRequest
asMultipart()
Indicate the request is a multi-part form request.
at line 414
PendingRequest
bodyFormat(string $format)
Specify the body format of the request.
at line 426
PendingRequest
withQueryParameters(array $parameters)
Set the given query parameters in the request URI.
at line 440
PendingRequest
contentType(string $contentType)
Specify the request's content type.
at line 452
PendingRequest
acceptJson()
Indicate that JSON should be returned by the server.
at line 462
PendingRequest
accept(string $contentType)
Indicate the type of content that should be returned by the server.
at line 472
PendingRequest
withHeaders(array $headers)
Add the given headers to the request.
at line 486
PendingRequest
withHeader(string $name, mixed $value)
Add the given header to the request.
at line 496
PendingRequest
replaceHeaders(array $headers)
Replace the given headers on the request.
at line 508
PendingRequest
withBasicAuth(string $username, string $password)
Specify the basic authentication username and password for the request.
at line 520
PendingRequest
withDigestAuth(string $username, string $password)
Specify the digest authentication username and password for the request.
at line 534
PendingRequest
withToken(string $token, string $type = 'Bearer')
Specify an authorization token for the request.
at line 546
PendingRequest
withUserAgent(bool|string $userAgent)
Specify the user agent for the request.
at line 558
PendingRequest
withUrlParameters(array $parameters = [])
Specify the URL parameters that can be substituted into the request URL.
at line 571
PendingRequest
withCookie(SetCookie $cookie)
Specify a cookie and its attributes for the request.
at line 591
PendingRequest
withCookies(array $cookies, string $domain)
Specify the cookies that should be included with the request.
at line 605
PendingRequest
maxRedirects(int $max)
Specify the maximum number of redirects to allow.
at line 623
PendingRequest
withoutRedirecting()
Indicate that redirects should not be followed.
at line 635
PendingRequest
withoutVerifying()
Indicate that TLS certificates should not be verified.
at line 651
PendingRequest
withDestinationPolicy(DestinationPolicy $policy)
Restrict the request's destinations to those the given policy allows.
The policy checks and pins every physical request, including each redirect, to the addresses it vetted. Faked requests and clients supplied through setClient() never reach it.
at line 665
ResolvedDestination
resolveDestination(DestinationPolicy $policy, string $url)
| internal |
Resolve and pin a destination within this request's timeout limits.
Hostname pins use an isolated transport; literal addresses can reuse connections. Disable automatic redirects and send the returned URI so its hostname matches the pins.
at line 695
PendingRequest
sink(resource|StreamInterface|string $to)
Specify the path where the body of the response should be stored.
at line 707
PendingRequest
timeout(float|int $seconds)
Specify the timeout (in seconds) for the request.
at line 719
PendingRequest
connectTimeout(float|int $seconds)
Specify the connect timeout (in seconds) for the request.
at line 733
PendingRequest
retry(array|int $times, Closure|int $sleepMilliseconds = 0, callable|null $when = null, bool $throw = true)
Specify the number of times the request should be attempted.
at line 752
PendingRequest
withOptions(array $options)
Replace the specified options on the request.
at line 765
PendingRequest
withMiddleware(callable $middleware)
Add new middleware the client handler stack.
at line 777
PendingRequest
prependMiddleware(callable $middleware)
Prepend new middleware to the client handler stack.
at line 789
PendingRequest
withRequestMiddleware(callable $middleware)
Add new request middleware the client handler stack.
at line 801
PendingRequest
withResponseMiddleware(callable $middleware)
Add new response middleware the client handler stack.
at line 813
PendingRequest
withAttributes(array $attributes)
Set arbitrary attributes to store with the request.
at line 823
array
attributes()
Get the attributes stored with the request.
at line 833
PendingRequest
withoutTelescope()
Indicate that Telescope should not record this request.
at line 844
PendingRequest
withTelescopeTags(array $tags)
Set Telescope tags for this request.
at line 854
PendingRequest
withTrace()
Indicate that OpenTelemetry should trace this request.
at line 864
PendingRequest
withoutTrace()
Indicate that OpenTelemetry should not trace this request.
at line 876
PendingRequest
withoutTracePropagation()
Indicate that trace context should not be automatically added to this request.
The request may still be traced locally.
at line 886
PendingRequest
beforeSending(callable $callback)
Add a new "before sending" callback to the request.
at line 899
PendingRequest
afterResponse(callable $callback)
Add a new callback to execute after the response is built.
at line 912
PendingRequest
throw(callable|null $callback = null)
Throw an exception if a server or client error occurs.
at line 925
PendingRequest
throwIf(bool|callable $condition, callable|null $callback = null)
Throw an exception if a server or client error occurred and the given condition evaluates to true.
at line 940
PendingRequest
throwUnless(bool|callable $condition, callable|null $callback = null)
Throw an exception if a server or client error occurred and the given condition evaluates to false.
at line 954
PendingRequest
dump()
Dump the request before sending.
at line 970
PendingRequest
dd()
Dump the request before sending and end the script.
at line 992
PromiseInterface|Response
get(string $url, Arrayable|array|JsonSerializable|string|null $query = null)
Issue a GET request to the given URL.
at line 1012
PromiseInterface|Response
head(string $url, Arrayable|array|JsonSerializable|string|null $query = null)
Issue a HEAD request to the given URL.
at line 1032
PromiseInterface|Response
query(string $url, Arrayable|array|JsonSerializable $data = [])
Issue a QUERY request to the given URL.
at line 1048
PromiseInterface|Response
post(string $url, Arrayable|array|JsonSerializable $data = [])
Issue a POST request to the given URL.
at line 1064
PromiseInterface|Response
patch(string $url, Arrayable|array|JsonSerializable $data = [])
Issue a PATCH request to the given URL.
at line 1080
PromiseInterface|Response
put(string $url, Arrayable|array|JsonSerializable $data = [])
Issue a PUT request to the given URL.
at line 1096
PromiseInterface|Response
delete(string $url, Arrayable|array|JsonSerializable $data = [])
Issue a DELETE request to the given URL.
at line 1121
PromiseInterface|Response
send(string $method, string $url, array $options = [])
Send the request to the given URL.
at line 1219
protected string
expandUrlParameters(string $url)
Substitute the URL parameters in the given URL.
at line 1233
protected array
parseHttpOptions(array $options)
Parse the given HTTP options and set the appropriate additional options.
at line 1281
protected array
parseMultipartBodyFormat(array $data)
Parse multi-part form data.
at line 1299
protected array
wrapMultipartStreams(array $multipart)
Wrap the multipart stream resources in PSR-7 streams so they are not closed between retry attempts.
at line 1326
protected void
rewindMultipartStreams(array $options)
Rewind the seekable multipart streams so each attempt contains the full part contents.
at line 1346
protected PromiseInterface
makePromise(string $method, string $url, array $options = [], int $attempt = 1)
Send an asynchronous request to the given URL.
at line 1404
protected mixed
handlePromiseResponse(Response|Throwable $response, string $method, string $url, array $options, int $attempt)
Handle the response of an asynchronous request.
at line 1468
protected int
getMaximumAttempts()
Get the maximum number of attempts for the request.
at line 1478
protected int|float
retryDelayInMilliseconds(int $attempt, mixed $exception)
Get the delay in milliseconds before the next retry attempt.
at line 1490
protected PromiseInterface|ResponseInterface
sendRequest(string $method, string $url, array $options = [])
Send a request either synchronously or asynchronously.
at line 1548
protected array
parseRequestData(string $method, string $url, array $options)
Get the request data as an array so that we can attach it to the request for convenient assertions.
at line 1587
protected array
normalizeRequestOptions(array $options)
Normalize the given request options.
at line 1647
protected array
normalizeHeaderValues(array $headers)
Normalize the given header values.
at line 1668
protected string|array
normalizeHeaderValue(mixed $value)
Normalize the given header value.
at line 1701
protected array
normalizeNonFiniteFloatValues(array $values)
Normalize non-finite floats within a nested array.
at line 1717
protected array
normalizeMultipartOption(array $multipart)
Normalize the given multipart option.
at line 1760
protected array
normalizeMultipartHeaders(array $multipart)
Normalize the given multipart headers.
at line 1787
protected mixed
normalizeRequestOptionValue(mixed $value)
Normalize the given request option value.
at line 1815
protected array|string|null
normalizeQuery(mixed $query)
Normalize a query supplied to a GET request.
at line 1829
protected mixed
normalizeStructuredDataValue(mixed $value)
Normalize nested structured data values.
at line 1855
protected string
normalizeScalarString(bool|float|int|string $value)
Normalize a scalar to a string without triggering PHP 8.5 non-finite float warnings.
at line 1873
protected void
ensureValidRequestBody(mixed $body)
Ensure the given request body can be passed to Guzzle.
at line 1883
protected Response
populateResponse(Response $response)
Populate the given response with additional data.
at line 1895
ClientInterface
buildClient()
Build the Guzzle client.
at line 1903
ClientInterface
createClient(HandlerStack $handlerStack)
Create a new Guzzle client.
at line 1914
HandlerStack
buildHandlerStack()
Build the Guzzle client handler stack.
at line 1955
protected callable
newIsolatedHandler()
Create a request-owned transport for destination pinning.
at line 1964
HandlerStack
pushHandlers(HandlerStack $handlerStack)
Add the necessary handlers to the given handler stack.
at line 1991
protected Closure
buildPreparedBodyHandler()
Build the prepared body tracking handler.
at line 2005
Closure
buildBeforeSendingHandler()
Build the before sending handler.
at line 2030
Closure
buildRecorderHandler()
Build the recorder handler.
at line 2069
Closure
buildStubHandler()
Build the stub handler.
at line 2130
protected Closure
sinkStubHandler(mixed $sink)
Get the sink stub handler callback.
A sink that stops accepting the body fails the request as a transport would, with the response, so the callback also takes the request. A subclass decorating the callback may still pass the response alone, as Laravel's callback takes it; the request being sent is used then.
at line 2187
protected Closure
buildDatabaseReleaseHandler()
Return idle database sessions before waiting for an external service.
at line 2195
protected Closure
buildDestinationPolicyHandler()
Build the destination policy handler.
at line 2220
protected PromiseInterface
sendToPolicyDestination(callable $handler, DestinationPolicy $policy, RequestInterface $request, array $options)
Send one physical request to the addresses the destination policy vetted.
at line 2353
RequestInterface
runBeforeSendingCallbacks(RequestInterface $request, array $options)
Execute the "before sending" callbacks.
at line 2400
array
mergeOptions(...$options)
Replace the given options with the current request options.
at line 2421
protected Response
newResponse(ResponseInterface $response)
Create a new response instance using the given PSR response.
at line 2437
protected Response
runAfterResponseCallbacks(Response $response)
Execute the "after response" callbacks.
at line 2455
PendingRequest
stub(callable|Collection $callback)
Register a stub callable that will intercept requests and be able to return stub responses.
at line 2469
PendingRequest
preventStrayRequests(bool $prevent = true)
Indicate that an exception should be thrown if any request is not faked.
at line 2481
PendingRequest
allowStrayRequests(array $only)
Allow stray, unfaked requests for specific URL patterns.
at line 2491
bool
isAllowedRequestUrl(string $url)
Determine if the given URL is allowed as a stray request.
at line 2517
PendingRequest
async(bool $async = true)
Toggle asynchronicity in requests.
at line 2528
PromiseInterface|null
getPromise()
Retrieve the pending request promise.
at line 2536
protected void
dispatchRequestSendingEvent()
Dispatch the RequestSending event if a dispatcher is available.
at line 2546
protected void
dispatchResponseReceivedEvent(Response $response)
Dispatch the ResponseReceived event if a dispatcher is available.
at line 2558
protected void
dispatchConnectionFailedEvent(Request $request, ConnectionException $exception)
Dispatch the ConnectionFailed event if a dispatcher is available.
at line 2570
PendingRequest
truncateExceptionsAt(int $length)
Indicate that request exceptions should be truncated to the given length.
at line 2582
PendingRequest
dontTruncateExceptions()
Indicate that request exceptions should not be truncated.
at line 2592
protected ResponseInterface|null
responseFromException(Throwable $e)
Get the PSR-7 response carried by the given exception, if any.
at line 2602
protected void
marshalTransportException(TransferException $e)
Handle the given transport exception.
at line 2619
protected void
marshalTransportExceptionWithResponse(TransferException $e, ResponseInterface $response)
Handle the given transport exception that carried a response.
at line 2629
protected Response|ConnectionException
marshalAsyncTransportExceptionWithResponse(Throwable $e, ResponseInterface $response)
Preserve an asynchronous transfer failure even when its response status is successful.
at line 2643
PendingRequest
setClient(ClientInterface $client)
Set the client instance.
The client owns its whole handler stack, so destination policies do not apply to it.
at line 2657
PendingRequest
setHandler(callable $handler)
Create a new client instance using the given handler.
Destination-restricted requests reject custom handlers, since their pins only bind the cURL handler.
at line 2667
array
getOptions()
Get the pending request options.
at line 2681
PendingRequest
connection(string $connection, array|null $config = null)
Set the pending request connection.
at line 2700
string|null
getConnection()
Get the pending request connection.
at line 2708
array|null
getConnectionConfig()
Get the pending request connection configuration.
at line 2716
protected array
connectionOptions()
Get the effective request-option preset for the selected connection.
at line 2732
protected array
mergeOptionLayers(array ...$layers)
Merge HTTP option layers using the request-option merge rules.
at line 2757
protected mixed
mergeOptionValue(mixed $current, mixed $value, bool $mergeable = false)
Merge an option value from a later layer over the current value.
Maps merge by key, with later values winning. Lists such as header values, auth credentials and redirect protocols are replaced whole, since merging them by index would mix entries from both layers. The lists of a mergeable option, such as multipart parts, accumulate instead.
at line 2792
protected void
validateRequestOptions(array $options, string $source)
Reject options whose ownership belongs to dedicated APIs.
at line 2800
static void
flushState()
Flush all static state.