HTTP requests to external sources
The PHP library "Guzzle" is available in TYPO3 as a feature-rich solution for creating HTTP requests based on the PSR-7 interfaces.
Guzzle automatically detects the underlying adapters available on the system, such as cURL or stream wrappers, and chooses the best solution for the system.
A TYPO3-specific PHP class named
\TYPO3\ is
present as a simplified wrapper for accessing Guzzle clients.
All options available under
$GLOBALS are
automatically applied to the Guzzle clients when using the
Request
class. The options are a subset of the available options from Guzzle, but can be
extended.
Although Guzzle can handle Promises/A+ and asynchronous requests, it currently
serves as a drop-in replacement for the previous mixed options and
implementations within
General and a PSR-7-based API for
HTTP requests.
The TYPO3-specific wrapper
General uses Guzzle for
remote files, eliminating the need to directly configure settings based on
specific implementations such as stream wrappers or cURL.
Basic usage
The
Request class can be used like this:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Http;
use TYPO3\CMS\Core\Http\RequestFactory;
final readonly class MeowInformationRequester
{
private const API_URL = 'https://catfact.ninja/fact';
// We need the RequestFactory for creating and sending a request,
// so we inject it into the class using constructor injection.
public function __construct(
private RequestFactory $requestFactory,
) {}
/**
* @throws \JsonException
* @throws \RuntimeException
*/
public function request(): string
{
// Additional headers for this specific request
// See: https://docs.guzzlephp.org/en/stable/request-options.html
$additionalOptions = [
'headers' => ['Cache-Control' => 'no-cache'],
'allow_redirects' => false,
];
// Get a PSR-7-compliant response object
$response = $this->requestFactory->request(
self::API_URL,
'GET',
$additionalOptions,
);
if ($response->getStatusCode() !== 200) {
throw new \RuntimeException(
'Returned status code is ' . $response->getStatusCode(),
4696129526,
);
}
if ($response->getHeaderLine('Content-Type') !== 'application/json') {
throw new \RuntimeException(
'The request did not return JSON data',
2722965511,
);
}
// Get the content as a string on a successful request
$content = $response->getBody()->getContents();
$result = json_decode($content, true, flags: JSON_THROW_ON_ERROR);
if (!is_array($result) || !isset($result['fact']) || !is_scalar($result['fact'])) {
throw new \RuntimeException('The service returned an unexpected format.', 1666413230);
}
return (string)$result['fact'];
}
}
A POST request passes the data in the options. The following class sends a
first and a last name as form data, URL-encoded like an HTML form does. To send
raw data instead, use the option body. Guzzle sends only one of the two:
when both are set, form_ replaces body.
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Http;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Core\Http\RequestFactory;
final readonly class NewsletterSubscriber
{
private const API_URL = 'https://newsletter.example.org/subscribe';
public function __construct(
private RequestFactory $requestFactory,
) {}
public function subscribe(string $first, string $last): ResponseInterface
{
// Send the data URL-encoded, like an HTML form does. To send raw data,
// use the option 'body' instead.
$additionalOptions = [
'form_params' => [
'first_name' => $first,
'last_name' => $last,
],
];
return $this->requestFactory->request(
self::API_URL,
'POST',
$additionalOptions,
);
}
}
Extension authors are advised to use the
Request class instead of
using the Guzzle API directly in order to ensure a clear upgrade path when
updates to the underlying API need to be done.
Custom middleware handlers
Guzzle accepts a stack of custom middleware handlers which can be configured
in
$GLOBALS as an array. If a
custom configuration is specified, the default handler stack will be extended
and not overwritten.
A Guzzle middleware is a callable that takes the next handler and returns a new
one. The following middleware adds an X- header with a random value
to every outgoing request, so that the logs of the receiving service can be
matched with the logs of TYPO3:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Http\Middleware;
use Psr\Http\Message\RequestInterface;
/**
* Guzzle middleware that gives each outgoing request an ID, so that the
* logs of the receiving service can be matched with the logs of TYPO3
*/
final class RequestIdMiddleware
{
public function __invoke(callable $handler): callable
{
return static fn(RequestInterface $request, array $options) => $handler(
$request->withHeader('X-Request-Id', bin2hex(random_bytes(8))),
$options,
);
}
}
Add it to the handler stack in the system configuration. The array key names the middleware in the stack:
HTTP utility methods
TYPO3 provides a small set of helper methods related to HTTP Requests in the class
Http:
HttpUtility::buildUrl
Creates a URL string from an array containing the URL parts, such as those
output by
parse_.
HttpUtility::buildQueryString
The
build method is an enhancement to the PHP function
http_. It implodes multidimensional parameter arrays and
properly encodes parameter names as well as values into a valid query string
with an optional prepend of
?
or
&
.
If the query is not empty, ? or & are prepended in the correct sequence.
Empty parameters are skipped.