Comment on page
HTTP data provider

Setting up your data connection
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/');
Configuration
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.
Authentication
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'
]);
See Symfony HTTP authentication.
It's also common for APIs to also set API tokens via query string parameters (see below).
Query String Parameters
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'
    ]
]);
Headers
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'
    ]
]);
Symfony HttpClient
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);
Making requests
get
Run a GET request.
Parameters
string $uri URI relative to base URI
array $queryParams Array of query params to send with GET request
array $options HTTP options to use for this request (these override default HTTP options)
Returns an object of type Strata\Data\Http\Response\CacheableResponse
post
Run a POST request.
Parameters
string $uri URI relative to base URI
array $postData Array of data to send with POST request
array $options HTTP options to use for this request (these override default HTTP options)
Returns an object of type Strata\Data\Http\Response\CacheableResponse
head
Run a HEAD request.
Parameters
string $uri URI relative to base URI
array $options HTTP options to use for this request (these override default HTTP options)
Returns an object of type Strata\Data\Http\Response\CacheableResponse
Cacheable responses
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";
}
See caching for more.
exists
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 URI
array $options HTTP options to use for this request (these override default HTTP options)
Returns a boolean
getRss
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 URI
array $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.
See docs on retrieving feed information and retrieving entry item information.
Concurrent requests
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.
Manually running concurrent requests
You can also manually run concurrent requests by making a request in two steps: first prepare the request, then run it.
Using the example in the Symfony docs for concurrent requests this can be done as so:
$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.
Running requests manually
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().
prepareRequest
Prepare request (but do not run it).
Parameters
string $method HTTP method
string $uri URI relative to base URI
array $options HTTP options to use for this request (these override default HTTP options)
Returns an object of type Strata\Data\Http\Response\CacheableResponse
runRequest
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
Suppress exceptions on error
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);
Retrieving data - Previous
Data providers
Next - Retrieving data
GraphQL data provider
Last modified 9mo ago