VOOZH about

URL: https://deepwiki.com/hypervel/http-client/5.1-request-configuration

⇱ Request Configuration | hypervel/http-client | DeepWiki

Loading...
Loading...
Menu

Request Configuration

This page documents all methods available on the PendingRequest class for configuring HTTP requests before execution. This covers headers, authentication, timeouts, redirects, SSL verification, retry logic, and other request options.

For information about request body formats (JSON, form data, multipart), see Request Body Formats. For retry logic details, see Retry Logic and Error Recovery. For middleware configuration, see Middleware and Handler Stack.

Configuration Overview

All request configuration methods on PendingRequest return $this to enable fluent method chaining. Configuration is stored in the $options property and merged with Guzzle's request options when the request is executed.



Sources: src/PendingRequest.php38-210




URL Configuration


Base URL


The baseUrl() method sets a base URL that will be prepended to all relative URLs in subsequent requests.




Method:


    

  • baseUrl(string $url): static - Sets the base URL for the request
    • 



When a request is sent, if the URL does not start with http:// or https://, the base URL is prepended. The implementation trims and concatenates the base URL with the request URL.


Sources: src/PendingRequest.php215-220 src/PendingRequest.php715-717


URL Parameters


The withUrlParameters() method sets parameters that can be substituted into URL templates using RFC 6570 URI Template syntax.


Method:


    

  • withUrlParameters(array $parameters = []): static - Sets URL template parameters
    • 



URL parameters are stored in the $urlParameters property and expanded using GuzzleHttp\UriTemplate\UriTemplate::expand() before the request is sent.

















PropertyTypeDescription
$urlParametersarrayParameters that can be substituted into the URL


Sources: src/PendingRequest.php62-63 src/PendingRequest.php412-417 src/PendingRequest.php799-802




Headers and Content Type


Setting Headers




Methods:


    

  • withHeaders(array $headers): static - Adds headers using recursive merge
    • 

  • withHeader(string $name, mixed $value): static - Adds a single header
    • 

  • replaceHeaders(array $headers): static - Replaces headers using non-recursive merge
    • 

  • contentType(string $contentType): static - Sets the Content-Type header
    • 

  • accept(string $contentType): static - Sets the Accept header
    • 

  • acceptJson(): static - Sets Accept header to application/json
    • 



The distinction between withHeaders() and replaceHeaders() is important:


    

  • withHeaders() uses array_merge_recursive, which combines duplicate keys
    • 

  • replaceHeaders() uses array_merge, which replaces duplicate keys
    • 



Sources: src/PendingRequest.php316-321 src/PendingRequest.php326-337 src/PendingRequest.php342-367


User Agent


Method:


    

  • withUserAgent(bool|string $userAgent): static - Sets the User-Agent header
    • 



Sources: src/PendingRequest.php402-407




Authentication


Authentication Methods Overview




Methods:


    

  • withBasicAuth(string $username, string $password): static - Sets HTTP Basic authentication
    • 

  • withDigestAuth(string $username, string $password): static - Sets HTTP Digest authentication
    • 

  • withToken(string $token, string $type = 'Bearer'): static - Sets token-based authentication
    • 



Authentication Implementation Details



























MethodStorage LocationFormat
withBasicAuth()$options['auth'][$username, $password]
withDigestAuth()$options['auth'][$username, $password, 'digest']
withToken()$options['headers']['Authorization']"{$type} {$token}"


The token type defaults to 'Bearer' but can be customized for other authentication schemes.


Sources: src/PendingRequest.php372-397




Cookies


Method:


    

  • withCookies(array $cookies, string $domain): static - Sets cookies for the request
    • 



Cookies are stored using GuzzleHttp\Cookie\CookieJar::fromArray() and merged into the $options['cookies'] array. The domain parameter specifies which domain the cookies belong to.


Sources: src/PendingRequest.php422-429




Query Parameters


Method:


    

  • withQueryParameters(array $parameters): static - Adds query string parameters to the request URI
    • 



Query parameters are merged recursively into $options['query']. These are separate from the query parameters that can be passed directly to HTTP method calls like get().


Sources: src/PendingRequest.php304-311




Timeouts and Connection Settings


Timeout Configuration




Methods:


    

  • timeout(float|int $seconds): static - Sets the request timeout in seconds
    • 

  • connectTimeout(float|int $seconds): static - Sets the connection timeout in seconds
    • 



Default Timeout Values


The constructor sets default timeouts:



























OptionDefault ValueDescription
timeout30 secondsMaximum time for entire request
connect_timeout10 secondsMaximum time to establish connection
crypto_methodSTREAM_CRYPTO_METHOD_TLSv1_2_CLIENTTLS version


Sources: src/PendingRequest.php195-200 src/PendingRequest.php476-491




Redirects and SSL/TLS


Redirect Configuration


Methods:


    

  • maxRedirects(int $max): static - Sets maximum number of redirects to follow
    • 

  • withoutRedirecting(): static - Disables automatic redirect following
    • 



The maxRedirects() method sets $options['allow_redirects']['max'], while withoutRedirecting() sets $options['allow_redirects'] to false.


Sources: src/PendingRequest.php434-449


SSL/TLS Verification


Method:


    

  • withoutVerifying(): static - Disables SSL certificate verification
    • 



This sets $options['verify'] to false. Warning: This should only be used in development or testing environments as it makes connections vulnerable to man-in-the-middle attacks.


Sources: src/PendingRequest.php454-459




Response Configuration


Sink Option


Method:


    

  • sink(resource|string $to): static - Specifies where the response body should be stored
    • 



The sink option allows streaming the response body directly to a file or stream resource instead of loading it into memory. The $to parameter can be:


    

  • A string representing a file path
    • 

  • A resource handle (e.g., from fopen())
    • 



Sources: src/PendingRequest.php466-471




Retry Logic


Method:


    

  • retry(array|int $times, Closure|int $sleepMilliseconds = 0, ?callable $when = null, bool $throw = true): static
    • 



The retry configuration controls how failed requests are retried. See Retry Logic and Error Recovery for detailed documentation.


Retry Parameters
































ParameterTypeDescription
$timesarray|intNumber of retry attempts
$sleepMillisecondsClosure|intDelay between retries in milliseconds
$when?callableCallback to determine if retry should occur
$throwboolWhether to throw exception after all retries fail


Retry Properties




Sources: src/PendingRequest.php107-126 src/PendingRequest.php496-508




Error Handling


Exception Throwing Configuration




Methods:


    

  • throw(?callable $callback = null): static - Throws exception on HTTP errors, with optional callback
    • 

  • throwIf(bool|callable $condition): static - Conditionally throws exception based on condition
    • 

  • throwUnless(bool|callable $condition): static - Throws exception unless condition is true
    • 



The callbacks are invoked when a server or client error occurs. The $throwIfCallback is evaluated first to determine if an exception should be thrown, and $throwCallback is executed before the exception is thrown.


Sources: src/PendingRequest.php97-104 src/PendingRequest.php566-591




Debugging


Debug Methods


Methods:


    

  • dump(): static - Dumps the request and options before sending
    • 

  • dd(): static - Dumps the request and options, then terminates execution
    • 



Both methods use Symfony\Component\VarDumper\VarDumper to output request details. They work by adding a callback to the $beforeSendingCallbacks collection.




Sources: src/PendingRequest.php596-621




Advanced Options


Custom Options


Method:


    

  • withOptions(array $options): static - Merges custom Guzzle options into the request
    • 



This method allows setting any Guzzle request option. The merging behavior is sophisticated:


    

  1. Options in the $mergeableOptions list are merged recursively
    2. 

  2. All other options are replaced
    3. 



Mergeable Options


The following options are merged recursively rather than replaced:




This prevents accidental overwriting of headers, cookies, and other accumulated configuration when adding new options.


Sources: src/PendingRequest.php175-182 src/PendingRequest.php513-521


Before Sending Callbacks


Method:


    

  • beforeSending(callable $callback): static - Registers a callback to execute before the request is sent
    • 



The callback receives three arguments:


    

  1. Request $request - The wrapped request object
    2. 

  2. array $options - The Guzzle request options
    3. 

  3. PendingRequest $pendingRequest - The current PendingRequest instance
    4. 



Callbacks can modify the request by returning a RequestInterface or Request instance.


Sources: src/PendingRequest.php130-131 src/PendingRequest.php556-561 src/PendingRequest.php1171-1189




Connection Management


Method:


    

  • connection(string $connection, ?array $config = null): static - Sets the connection name and optional configuration
    • 



Connections enable connection pooling and named client configurations. See Connection Management for details.


Properties:


    

  • $connection - Stores the connection name
    • 

  • $connectionConfig - Stores the connection-specific configuration
    • 



Sources: src/PendingRequest.php164-171 src/PendingRequest.php1313-1334




Options Storage and Merging


Options Array Structure


The $options property stores all Guzzle request options. Configuration methods modify this array, which is eventually passed to the Guzzle client.




Merging Process


The mergeOptions() method combines instance options with request-specific options:




Sources: src/PendingRequest.php1194-1200




Configuration Retrieval


Method:


    

  • getOptions(): array - Returns the current request options
    • 



This method provides read access to the configured options for inspection or testing purposes.


Sources: src/PendingRequest.php1305-1308




Summary Table























































































CategoryMethodsKey Options
URLbaseUrl(), withUrlParameters()$baseUrl, $urlParameters
HeaderswithHeaders(), withHeader(), replaceHeaders(), contentType(), accept(), acceptJson()$options['headers']
AuthenticationwithBasicAuth(), withDigestAuth(), withToken()$options['auth'], $options['headers']['Authorization']
User AgentwithUserAgent()$options['headers']['User-Agent']
CookieswithCookies()$options['cookies']
QuerywithQueryParameters()$options['query']
Timeoutstimeout(), connectTimeout()$options['timeout'], $options['connect_timeout']
RedirectsmaxRedirects(), withoutRedirecting()$options['allow_redirects']
SSL/TLSwithoutVerifying()$options['verify']
Responsesink()$options['sink']
Retryretry()$tries, $retryDelay, $retryThrow, $retryWhenCallback
Error Handlingthrow(), throwIf(), throwUnless()$throwCallback, $throwIfCallback
Debuggingdump(), dd()$beforeSendingCallbacks
AdvancedwithOptions(), beforeSending()$options, $beforeSendingCallbacks
Connectionconnection()$connection, $connectionConfig


Sources: src/PendingRequest.php1-1336