Comment on page
HTTP data provider
Setup the Http data provider, you need to set a base URI as the first argument:
use Strata\Data\Http\Http;
$api = new Http('https://example.com/');
This then runs all future requests relative to this base URI. For example:
// Makes a request to https://example.com/my-url
$response = $api->get('my-url');
To change the base URI just use:
$api->setBaseUri('https://new.com/');
You can configure the data provider with default HTTP options in a number of ways.
You can pass
$options
array when creating a new Http
object:$api = new Http('https://example.com/', $options);
You can also pass
$options
array when setting the current base URI:$api->setBaseUri('https://example.com/', $options);
Please note this overwrites any previously set default HTTP options.
See Symfony HttpClient configuration for a reference for all valid options. Common options appear below.
Set basic authentication:
$api = new Http('https://example.com/', [
'auth_basic' => 'the-username:the-password'
]);
Set a bearer authentication token:
$api = new Http('https://example.com/', [
'auth_bearer' => 'my-token'
]);
It's also common for APIs to also set API tokens via query string parameters (see below).
You can set any query string params to send with all requests, e.g. an auth token, via the
query
associative array:$api = new Http('https://example.com/', [
'query' => [
'auth_token' => 'ABC123'
]
]);
You can set any headers to send with all requests, e.g. the user agent, via the
headers
associative array:$api = new Http('https://example.com/', [
'headers' => [
'User-Agent' => 'my-custom-application'
]
]);
The
Http
data provider uses Symfony HttpClient to make requests. This is automatically created when it's needed. If you need to, you can set this up yourself and set via setHttpClient()
.An example usage would be if you want to set up a scoping client to setup default options for different URL patterns:
$client = HttpClient::create();
$client = new ScopingHttpClient($client, [
// the options defined as values apply only to the URLs matching
// the regular expressions defined as keys
'https://api\.github\.com/' => [
'headers' => [
'Accept' => 'application/vnd.github.v3+json',
'Authorization' => 'token ' . $githubToken,
],
],
// ...
]);
$api->setHttpClient($client);
Run a GET request.
- Parameters
string $uri
URI relative to base URIarray $queryParams
Array of query params to send with GET requestarray $options
HTTP options to use for this request (these override default HTTP options)
- Returns an object of type
Strata\Data\Http\Response\CacheableResponse
Run a POST request.
- Parameters
string $uri
URI relative to base URIarray $postData
Array of data to send with POST requestarray $options
HTTP options to use for this request (these override default HTTP options)
- Returns an object of type
Strata\Data\Http\Response\CacheableResponse
Run a HEAD request.
- Parameters
string $uri
URI relative to base URIarray $options
HTTP options to use for this request (these override default HTTP options)
- Returns an object of type
Strata\Data\Http\Response\CacheableResponse
Most requests return responses as objects of type
CacheableResponse
. These are identical to the standard Symfony response object with one additional method isHit()
which lets you know whether this response was returned from the cache or run live.$response = $api->get('url-path');
if ($response->isHit()) {
echo "HIT";
} else {
echo "MISS";
}
You can use the
exists()
method to simply test a URL endpoint returns a 200 successful status code.$api = new Http('https://http2.akamai.com/demo/');
$result = $api->exists('tile-101.png');
- Parameters
string $uri
URI relative to base URIarray $options
HTTP options to use for this request (these override default HTTP options)
- Returns a boolean
You can use the
getRss()
method to retrieve and decode an RSS feed.$http = new Http('https://example.com/');
$feed = $http->getRss('feed.rss');
foreach ($feed as $item) {
$title = $item->getTitle();
$link = $item->getLink();
}
- Parameters
string $uri
URI relative to base URIarray $options
HTTP options to use for this request (these override default HTTP options)
- Returns an iterable object of type
Laminas\Feed\Reader\Feed\FeedInterface
This uses Laminas Feed to decode the RSS feed, this supports RSS and Atom feeds of any version, including RDF/RSS 1.0, RSS 2.0, Atom 0.3, and Atom 1.0.
You can run a bulk set of GET requests quickly and efficiently by passing an array of URIs to the
getConcurrent()
method. This returns a generator which can be looped over with foreach
.$uris = [
'https://example.com/uri-1',
'https://example.com/uri-2',
];
/** @var ResponseInterface $response */
foreach ($api->getConcurrent($uris) as $response) {
// ...
}
You can pass default options to use with all requests via the second parameter
array $options
.foreach ($api->getConcurrent($uris, $options) as $response) { }
If each request needs custom options (e.g. query params) then you can pass an array of arrays, with each request having two keys (
uri
, options
).$uris = [
['uri' => 'https://example.com/uri-1', 'options' => ['query' => ['page' => 1]]],
['uri' => 'https://example.com/uri-2', 'options' => ['query' => ['page' => 2]]],
];
foreach ($api->getConcurrent($uris) as $response) { }
If any default options are passed to
getConcurrent()
these are used with requests and merged with any request options set for individual requests. Please note, options in individual requests override default options.You can also manually run concurrent requests by making a request in two steps: first prepare the request, then run it.
$api = new Http('https://http2.akamai.com/demo/');
$responses = [];
for ($i = 0; $i < 379; ++$i) {
$uri = "tile-$i.png";
$responses[] = $api->prepareRequest('GET', $uri);
}
foreach ($responses as $response) {
$response = $api->runRequest($response);
// ...
}
The
runRequest()
method checks the status code to ensure the request has run successfully.All requests run the
prepareRequest()
and runRequest()
, this is to help support concurrent requests. You can use these methods directly, but it's recommended to use a helper method above such as get()
.Prepare request (but do not run it).
- Parameters
string $method
HTTP methodstring $uri
URI relative to base URIarray $options
HTTP options to use for this request (these override default HTTP options)
- Returns an object of type
Strata\Data\Http\Response\CacheableResponse
Run a request (note Symfony HttpClient is lazy loading so this still won't actually run a HTTP request until content is accessed).
- Parameters
CacheableResponse $response
Response to run
- Returns an object of type
Strata\Data\Http\Response\CacheableResponse
The default behaviour of is to throw exceptions on HTTP or JSON decoding errors (e.g. if a request does not return a 200 status), though this can be suppressed. It can be useful to do this for sub-requests which you don't want to stop the master HTTP request.
You can do this via:
$data->suppressErrors();
Which disables exceptions for
TransportExceptionInterface
, HttpExceptionInterface
and FailedRequestException
exceptions.You can turn off this error suppression via:
$data->suppressErrors(false);
Last modified 9mo ago