Request options

The second argument to fetch() is the init array. This follows the browser Fetch style where possible, but because this is server-side PHP, not every browser option has a meaningful implementation.

$http->fetch("https://example.com/api", [
	"method" => "POST",
	"headers" => [
		"Accept" => "application/json",
	],
]);

Below we will look at each supported option in turn.

method

Use method to set the HTTP method.

$http->fetch("https://postman-echo.com/post", [
	"method" => "POST",
]);

If omitted, the default request method is GET.

headers

Headers are supplied as an associative array.

$http->fetch("https://example.com/api", [
	"headers" => [
		"Accept" => "application/json",
		"X-Request-Id" => "abc123",
	],
]);

If a header has multiple values, an array of values may be provided.

body

The request body may be a string, associative array, or GT\Http\FormData.

Sending a string body

$http->fetch("https://example.com/api", [
	"method" => "POST",
	"headers" => [
		"Content-Type" => "application/json",
	],
	"body" => json_encode(["name" => "Ada"]),
]);

Sending form data

use GT\Http\FormData;

$formData = new FormData();
$formData->set("name", "Mark Zuckerberg");
$formData->set("email", "[email protected]");

$http->fetch("https://postman-echo.com/post", [
	"method" => "POST",
	"body" => $formData,
]);

Uploading files

If a FormData item contains a SplFileObject or GT\Http\File, it will be prepared for cURL file upload automatically.

See usage examples for a complete upload example.

redirect

The following redirect modes are supported:

• follow
• manual
• error

follow will follow redirects automatically. This is the default behaviour.

manual disables automatic redirect following, allowing us to inspect the redirect response ourselves.

error will throw a FetchException if the response attempts to redirect.

$http->fetch("https://example.com/redirect", [
	"redirect" => "error",
])->catch(function(Throwable $error) {
	echo $error->getMessage(), PHP_EOL;
});

referrer

The referrer option controls the Referer header.

$http->fetch("https://example.com/api", [
	"referrer" => "https://www.example.com/from-here",
]);

To omit the referrer:

$http->fetch("https://example.com/api", [
	"referrer" => "no-referrer",
]);

integrity

The integrity option allows subresource integrity checking against the completed response body.

$http->fetch("https://example.com/app.js", [
	"integrity" => "sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=",
]);

This is useful when we want to assert that a fetched resource matches a known hash before continuing.

keepalive

keepalive maps to cURL's TCP keepalive support.

$http->fetch("https://example.com/api", [
	"keepalive" => 1,
]);

signal

signal is used to abort a request before it completes.

use GT\Fetch\AbortController;

$controller = new AbortController();

$http->fetch("https://example.com/large-file.zip", [
	"signal" => $controller->signal,
]);

$controller->abort();

This is covered in more detail in cancelling requests.

Options that are recognised but not available server-side

Some browser fetch options do not currently have a meaningful implementation here and will throw a NotAvailableServerSideException when used:

• mode
• credentials
• referrerPolicy

The cache option is recognised, but is not currently implemented.

That means the safest approach is to treat this library as fetch-inspired rather than as a byte-for-byte browser implementation. Only the options that make sense server-side are active.

---

In the next section we will look at waiting for responses.