| Methods |
public
|
__construct(
UriInterface|Stringable|string|null $uri = null,
Arrayable<string, string[]|string>|iterable<string, string[]|string>|null $headers = null,
AccessTokenInterface|null $accessToken = null,
string $accessTokenHeaderName = HttpHeader::AUTHORIZATION,
string[] $sensitiveHeaders = HttpHeaderGroup::SENSITIVE,
string|null $mediaType = null,
string|null $userAgent = null,
bool $expectJson = true,
bool $postJson = true,
DateFormatterInterface|null $dateFormatter = null,
int-mask-of<FormDataFlag::*> $formDataFlags = FormDataFlag::PRESERVE_NUMERIC_KEYS | FormDataFlag::PRESERVE_STRING_KEYS,
int-mask-of<JSON_BIGINT_AS_STRING|JSON_INVALID_UTF8_IGNORE|JSON_INVALID_UTF8_SUBSTITUTE|JSON_OBJECT_AS_ARRAY|JSON_THROW_ON_ERROR> $jsonDecodeFlags = JSON_OBJECT_AS_ARRAY,
array<array{(CurlerMiddlewareInterface|HttpRequestHandlerInterface|(Closure(RequestInterface $request, Closure(RequestInterface): HttpResponseInterface $next, CurlerInterface $curler): ResponseInterface)), 1?: (string|null)}> $middleware = [],
CurlerPagerInterface|null $pager = null,
bool $alwaysPaginate = false,
CacheInterface|null $cacheStore = null,
bool $handleCookies = false,
string|null $cookiesCacheKey = null,
bool $cacheResponses = false,
bool $cachePostResponses = false,
(callable(RequestInterface $request, CurlerInterface $curler): (string[]|string))|null $cacheKeyCallback = null,
int<-1, max> $cacheLifetime = 3600,
bool $refreshCache = false,
int<0, max>|null $timeout = null,
bool $followRedirects = false,
int<-1, max>|null $maxRedirects = null,
bool $retryAfterTooManyRequests = false,
int<0, max> $retryAfterMaxSeconds = 300,
bool $throwHttpErrors = true,
)
Creates a new Curler object
Creates a new Curler object
Parameters after $uri are not covered by the Salient toolkit's backward
compatibility promise.
Parameters
| $uri |
Endpoint URI (cannot have query or fragment components)
|
| $headers |
Request headers
|
| $accessToken |
Access token applied to request headers
|
| $accessTokenHeaderName |
Name of access token header (default: "Authorization")
|
| $sensitiveHeaders |
Headers treated as sensitive (default: {@see HttpHeaderGroup::SENSITIVE})
|
| $mediaType |
Media type applied to request headers
|
| $userAgent |
User agent applied to request headers
|
| $expectJson |
Explicitly accept JSON-encoded responses and assume responses with no content type contain JSON
|
| $postJson |
Use JSON to encode POST/PUT/PATCH/DELETE data
|
| $dateFormatter |
Date formatter used to format and parse the endpoint's date and time values
|
| $formDataFlags |
Flags used to encode data for query strings and message bodies (default: {@see FormDataFlag::PRESERVE_NUMERIC_KEYS} | {@see FormDataFlag::PRESERVE_STRING_KEYS})
|
| $jsonDecodeFlags |
Flags used to decode JSON returned by the endpoint (default: {@see \JSON_OBJECT_AS_ARRAY})
|
| $middleware |
Middleware applied to the request handler stack
|
| $pager |
Pagination handler
|
| $alwaysPaginate |
Use the pager to process requests even if no pagination is required
|
| $cacheStore |
Cache store used for cookie and response caching instead of the {@see Cache} facade's underlying store
|
| $handleCookies |
Enable cookie handling
|
| $cookiesCacheKey |
Key to cache cookies under (cookie handling is implicitly enabled if given)
|
| $cacheResponses |
Cache responses to GET and HEAD requests (HTTP caching headers are ignored; USE RESPONSIBLY)
|
| $cachePostResponses |
Cache responses to repeatable POST requests (ignored if GET and HEAD request caching is disabled)
|
| $cacheKeyCallback |
Override values hashed and combined with request method and URI to create response cache keys (headers not in {@see HttpHeaderGroup::UNSTABLE} are used by default)
|
| $cacheLifetime |
Seconds before cached responses expire when caching is enabled (0 = cache indefinitely; -1 = do not cache; default: 3600)
|
| $refreshCache |
Replace cached responses even if they haven't expired
|
| $timeout |
Connection timeout in seconds (null = use underlying default of 300 seconds; default: null)
|
| $followRedirects |
Follow "Location" headers
|
| $maxRedirects |
Limit the number of "Location" headers followed (-1 = unlimited; 0 = do not follow redirects; null = use underlying default of 30; default: null)
|
| $retryAfterTooManyRequests |
Retry throttled requests when the endpoint returns a "Retry-After" header
|
| $retryAfterMaxSeconds |
Limit the delay between request attempts (0 = unlimited; default: 300)
|
| $throwHttpErrors |
Throw exceptions for HTTP errors
|
|
#
|
public
|
getUri(): UriInterface
Get the URI of the endpoint
Get the URI of the endpoint
Implements
|
#
|
public
|
getLastRequest(): ?RequestInterface
Get the last request sent to the endpoint or passed to middleware
Get the last request sent to the endpoint or passed to middleware
Implements
|
#
|
public
|
getLastResponse(): ?HttpResponseInterface
Get the last response received from the endpoint or returned by
middleware
Get the last response received from the endpoint or returned by
middleware
Implements
|
#
|
public
|
lastResponseIsJson(): bool
Check if the last response contains JSON-encoded data
Check if the last response contains JSON-encoded data
Implements
|
#
|
public
|
head(?array $query = null): HttpHeadersInterface
Send a HEAD request to the endpoint
Send a HEAD request to the endpoint
Implements
|
#
|
public
|
get(?array $query = null)
Send a GET request to the endpoint and return the body of the response
Send a GET request to the endpoint and return the body of the response
Implements
|
#
|
public
|
post($data = null, ?array $query = null)
Send a POST request to the endpoint and return the body of the response
Send a POST request to the endpoint and return the body of the response
Implements
|
#
|
public
|
put($data = null, ?array $query = null)
Send a PUT request to the endpoint and return the body of the response
Send a PUT request to the endpoint and return the body of the response
Implements
|
#
|
public
|
patch($data = null, ?array $query = null)
Send a PATCH request to the endpoint and return the body of the response
Send a PATCH request to the endpoint and return the body of the response
Implements
|
#
|
public
|
delete($data = null, ?array $query = null)
Send a DELETE request to the endpoint and return the body of the response
Send a DELETE request to the endpoint and return the body of the response
Implements
|
#
|
public
|
getP(?array $query = null): iterable
Send a GET request to the endpoint and iterate over response pages
Send a GET request to the endpoint and iterate over response pages
Implements
|
#
|
public
|
postP($data = null, ?array $query = null): iterable
Send a POST request to the endpoint and iterate over response pages
Send a POST request to the endpoint and iterate over response pages
Implements
|
#
|
public
|
putP($data = null, ?array $query = null): iterable
Send a PUT request to the endpoint and iterate over response pages
Send a PUT request to the endpoint and iterate over response pages
Implements
|
#
|
public
|
patchP($data = null, ?array $query = null): iterable
Send a PATCH request to the endpoint and iterate over response pages
Send a PATCH request to the endpoint and iterate over response pages
Implements
|
#
|
public
|
deleteP($data = null, ?array $query = null): iterable
Send a DELETE request to the endpoint and iterate over response pages
Send a DELETE request to the endpoint and iterate over response pages
Implements
|
#
|
public
|
postR(string $data, string $mediaType, ?array $query = null)
Send raw data to the endpoint in a POST request and return the body of
the response
Send raw data to the endpoint in a POST request and return the body of
the response
Implements
|
#
|
public
|
putR(string $data, string $mediaType, ?array $query = null)
Send raw data to the endpoint in a PUT request and return the body of the
response
Send raw data to the endpoint in a PUT request and return the body of the
response
Implements
|
#
|
public
|
patchR(string $data, string $mediaType, ?array $query = null)
Send raw data to the endpoint in a PATCH request and return the body of
the response
Send raw data to the endpoint in a PATCH request and return the body of
the response
Implements
|
#
|
public
|
deleteR(string $data, string $mediaType, ?array $query = null)
Send raw data to the endpoint in a DELETE request and return the body of
the response
Send raw data to the endpoint in a DELETE request and return the body of
the response
Implements
|
#
|
public
|
flushCookies()
Invalidate cached cookies
Invalidate cached cookies
Calling this method has no effect if the instance does not handle
cookies.
Implements
|
#
|
public
|
getHttpHeaders(): HttpHeadersInterface
Get request headers
|
#
|
public
|
getPublicHttpHeaders(): HttpHeadersInterface
Get request headers that are not considered sensitive
Get request headers that are not considered sensitive
Implements
|
#
|
public
|
hasAccessToken(): bool
Check if the instance has an access token
Check if the instance has an access token
Implements
|
#
|
public
|
isSensitiveHeader(string $name): bool
Check if a header is considered sensitive
Check if a header is considered sensitive
Implements
|
#
|
public
|
getMediaType(): ?string
Get the media type applied to request headers
Get the media type applied to request headers
Implements
|
#
|
public
|
getUserAgent(): string
Get the current user agent string
Get the current user agent string
Implements
|
#
|
public
|
expectsJson(): bool
Check if the instance explicitly accepts JSON-encoded responses and
assumes responses with no content type contain JSON
Check if the instance explicitly accepts JSON-encoded responses and
assumes responses with no content type contain JSON
Implements
|
#
|
public
|
postsJson(): bool
Check if the instance uses JSON to encode POST/PUT/PATCH/DELETE data
Check if the instance uses JSON to encode POST/PUT/PATCH/DELETE data
Implements
|
#
|
public
|
getDateFormatter(): ?DateFormatterInterface
Get the date formatter applied to the instance
Get the date formatter applied to the instance
Implements
|
#
|
public
|
getFormDataFlags(): int
Get form data flags applied to the instance
Get form data flags applied to the instance
Implements
|
#
|
public
|
getPager(): ?CurlerPagerInterface
Get the endpoint's pagination handler
Get the endpoint's pagination handler
Implements
|
#
|
public
|
alwaysPaginates(): bool
Check if the endpoint's pagination handler is used to process every
request
Check if the endpoint's pagination handler is used to process every
request
Implements
|
#
|
public
|
getCacheStore(): ?CacheInterface
Get the endpoint's cache store
Get the endpoint's cache store
Implements
|
#
|
public
|
hasCookies(): bool
Check if the instance handles cookies
Check if the instance handles cookies
Implements
|
#
|
public
|
hasResponseCache(): bool
Check if response caching is enabled
Check if response caching is enabled
Implements
|
#
|
public
|
hasPostResponseCache(): bool
Check if POST response caching is enabled
Check if POST response caching is enabled
Implements
|
#
|
public
|
getCacheLifetime(): int
Get the lifetime of cached responses, in seconds
Get the lifetime of cached responses, in seconds
Implements
|
#
|
public
|
refreshesCache(): bool
Check if the instance replaces cached responses even if they haven't
expired
Check if the instance replaces cached responses even if they haven't
expired
Implements
|
#
|
public
|
getTimeout(): ?int
Get the connection timeout applied to the instance, in seconds
Get the connection timeout applied to the instance, in seconds
Implements
|
#
|
public
|
followsRedirects(): bool
Check if the instance follows "Location" headers
Check if the instance follows "Location" headers
Implements
|
#
|
public
|
getMaxRedirects(): ?int
Get the maximum number of "Location" headers followed
Get the maximum number of "Location" headers followed
Implements
|
#
|
public
|
getRetryAfterTooManyRequests(): bool
Check if the instance retries throttled requests when the endpoint
returns a "Retry-After" header
Check if the instance retries throttled requests when the endpoint
returns a "Retry-After" header
Implements
|
#
|
public
|
getRetryAfterMaxSeconds(): int
Get the maximum delay between request attempts
Get the maximum delay between request attempts
Implements
|
#
|
public
|
throwsHttpErrors(): bool
Check if exceptions are thrown for HTTP errors
Check if exceptions are thrown for HTTP errors
Implements
|
#
|
public
|
replaceQuery($value, array $query)
Use the form data flags and date formatter applied to the instance to
replace the query string of a request or URI
Use the form data flags and date formatter applied to the instance to
replace the query string of a request or URI
Implements
|
#
|
public
|
withUri($uri)
Get an instance with the given endpoint URI
Get an instance with the given endpoint URI
An exception is thrown if the endpoint URI has a query or fragment.
Implements
|
#
|
public
|
withRequest(RequestInterface $request)
Apply the URI and headers of the given request to a copy of the instance
Apply the URI and headers of the given request to a copy of the instance
Implements
|
#
|
public
|
withAccessToken(?AccessTokenInterface $token, string $headerName = HttpHeader::AUTHORIZATION)
Get an instance that applies an access token to request headers
Get an instance that applies an access token to request headers
Implements
|
#
|
public
|
withSensitiveHeader(string $name)
Get an instance that treats a header as sensitive
Get an instance that treats a header as sensitive
Headers in {@see HttpHeaderGroup::SENSITIVE} are considered sensitive by
default.
Implements
|
#
|
public
|
withoutSensitiveHeader(string $name)
Get an instance that does not treat the given header as sensitive
Get an instance that does not treat the given header as sensitive
Implements
|
#
|
public
|
withMediaType(?string $type)
Get an instance that applies the given media type to request headers
Get an instance that applies the given media type to request headers
If $type is null (the default), Content-Type headers are
automatically applied to requests as needed.
Implements
|
#
|
public
|
withUserAgent(?string $userAgent)
Get an instance with the given user agent string
Get an instance with the given user agent string
If $userAgent is null, the default user agent string is restored.
Implements
|
#
|
public
|
withExpectJson(bool $expectJson = true)
Get an instance that explicitly accepts JSON-encoded responses and
assumes responses with no content type contain JSON
Get an instance that explicitly accepts JSON-encoded responses and
assumes responses with no content type contain JSON
Implements
|
#
|
public
|
withPostJson(bool $postJson = true)
Get an instance that uses JSON to encode POST/PUT/PATCH/DELETE data
Get an instance that uses JSON to encode POST/PUT/PATCH/DELETE data
Implements
|
#
|
public
|
withDateFormatter(?DateFormatterInterface $formatter)
Get an instance that uses the given date formatter to format and parse
the endpoint's date and time values
Get an instance that uses the given date formatter to format and parse
the endpoint's date and time values
Implements
|
#
|
public
|
withFormDataFlags(int $flags)
Get an instance with the given form data flags
Get an instance with the given form data flags
Form data flags are used to encode data for query strings and message
bodies.
{@see FormDataFlag::PRESERVE_NUMERIC_KEYS} and
{@see FormDataFlag::PRESERVE_STRING_KEYS} are applied by default.
Implements
|
#
|
public
|
withJsonDecodeFlags(int $flags)
Get an instance with the given json_decode() flags
Get an instance with the given json_decode() flags
{@see \JSON_OBJECT_AS_ARRAY} is applied by default.
{@see \JSON_THROW_ON_ERROR} is always applied and cannot be disabled.
Implements
|
#
|
public
|
withMiddleware($middleware, ?string $name = null)
Get an instance with the given middleware applied to the request handler
stack
Get an instance with the given middleware applied to the request handler
stack
Implements
|
#
|
public
|
withoutMiddleware($middleware)
Get an instance where the given middleware is not applied to requests
Get an instance where the given middleware is not applied to requests
Implements
|
#
|
public
|
withPager(?CurlerPagerInterface $pager, bool $alwaysPaginate = false)
Get an instance with the given pagination handler
Get an instance with the given pagination handler
Parameters
| $alwaysPaginate |
If true, the pager is used to process
requests even if no pagination is required.
|
Implements
|
#
|
public
|
withCacheStore(?CacheInterface $store = null)
Get an instance with the given cache store
Get an instance with the given cache store
If no $store is given, cookies and responses are cached in the default
cache store as needed.
Implements
|
#
|
public
|
withCookies(?string $cacheKey = null)
Get an instance that handles cookies
Get an instance that handles cookies
Implements
|
#
|
public
|
withoutCookies()
Get an instance that does not handle cookies
Get an instance that does not handle cookies
Implements
|
#
|
public
|
withResponseCache(bool $cacheResponses = true)
Get an instance that caches responses to GET and HEAD requests
Get an instance that caches responses to GET and HEAD requests
HTTP caching headers are ignored. USE RESPONSIBLY.
Implements
|
#
|
public
|
withPostResponseCache(bool $cachePostResponses = true)
Get an instance that caches responses to repeatable POST requests
Get an instance that caches responses to repeatable POST requests
{@see withResponseCache()} must also be called to enable caching.
Implements
|
#
|
public
|
withCacheKeyCallback(?callable $callback)
Get an instance that uses a callback to generate response cache keys
Get an instance that uses a callback to generate response cache keys
The callback's return value is hashed and combined with request method
and URI to create a response cache key.
Implements
|
#
|
public
|
withCacheLifetime(int $seconds)
Get an instance where cached responses expire after the given number of
seconds
Get an instance where cached responses expire after the given number of
seconds
3600 is applied by default.
{@see withResponseCache()} must also be called to enable caching.
Parameters
| $seconds |
-
0: cache responses indefinitely
-
-1: disable caching until the method is called again with $seconds
greater than or equal to 0
|
Implements
|
#
|
public
|
withRefreshCache(bool $refresh = true)
Get an instance that replaces cached responses even if they haven't
expired
Get an instance that replaces cached responses even if they haven't
expired
Implements
|
#
|
public
|
withTimeout(?int $seconds)
Get an instance with the given connection timeout
Get an instance with the given connection timeout
Parameters
| $seconds |
-
0: wait indefinitely
-
null (default): use the underlying client's default connection
timeout
|
Implements
|
#
|
public
|
withFollowRedirects(bool $follow = true)
Get an instance that follows "Location" headers
Get an instance that follows "Location" headers
Implements
|
#
|
public
|
withMaxRedirects(?int $redirects)
Get an instance that limits the number of "Location" headers followed
Get an instance that limits the number of "Location" headers followed
Parameters
| $redirects |
-
-1: allow unlimited redirects
-
0: disable redirects (same effect as withFollowRedirects(false))
-
null (default): use the underlying client's default redirect limit
|
Implements
|
#
|
public
|
withRetryAfterTooManyRequests(bool $retry = true)
Get an instance that retries throttled requests when the endpoint returns
a "Retry-After" header
Get an instance that retries throttled requests when the endpoint returns
a "Retry-After" header
Implements
|
#
|
public
|
withRetryAfterMaxSeconds(int $seconds)
Get an instance that limits the delay between request attempts
Get an instance that limits the delay between request attempts
300 is applied by default.
Parameters
| $seconds |
If 0, unlimited delays are allowed.
|
Implements
|
#
|
public
|
withThrowHttpErrors(bool $throw = true)
Get an instance that throws exceptions for HTTP errors
Get an instance that throws exceptions for HTTP errors
Implements
|
#
|
public
|
sendRequest(RequestInterface $request): HttpResponseInterface
Sends a PSR-7 request and returns a PSR-7 response.
Sends a PSR-7 request and returns a PSR-7 response.
Implements
|
#
|