CardDAV Client Library

HttpClientAdapter
in package

AbstractYes

Abstract base class for the internal HTTP client adapter.

This class intends to decouple the rest of this library from the underlying HTTP client library to allow for future replacement.

We aim at staying close to the PSR-18 definition of the Http ClientInterface, however, because Guzzle does currently not expose this interface (in particular its Psr7Request creation), compliance would mean to define an own implementation of the Psr7 Request Interface to create request objects, that would have to be deconstructed when interaction with Guzzle again.

So for now, this is not compliant with PSR-18 for simplicity, but we aim at staying close to the definition considering a potential later refactoring.

Tags
psalm-type

RequestOptions = array{ allow_redirects?: bool, body?: string, headers?: array<string, string | list> }

psalm-import-type

HttpOptions from Account

Table of Contents

Constants

NEEDED_AUTHNFO  : mixed = ['basic' => ['username', 'password'], 'digest'...
Defines which credential attributes are required for auth mechanisms.

Properties

$baseUri  : string
The base URI for requests.
$httpOptions  : HttpOptions
The HTTP options to use for communication, including authentication credentials.

Methods

isSameOrigin()  : bool
Checks whether two absolute URIs have the same origin, i.e. the same scheme, host and port.
mayAuthenticate()  : bool
Checks whether the credentials may be sent with a request to the given URI.
sendRequest()  : ResponseInterface
Sends an HTTP request and returns a PSR-7 response.
__construct()  : mixed
Constructs a HttpClientAdapter object.
checkCredentialsAvailable()  : bool
Checks if the needed credentials for an authentication scheme are available.
getOrigin()  : string|null
Provides a normalized string representation of the origin of an absolute URI.

Constants

NEEDED_AUTHNFO

Defines which credential attributes are required for auth mechanisms.

protected mixed NEEDED_AUTHNFO = ['basic' => ['username', 'password'], 'digest' => ['username', 'password'], 'bearer' => ['bearertoken']]

If a mechanism is not listed, it is assumed that no credentials are mandatory (e.g. GSSAPI/Kerberos).

Properties

$httpOptions

The HTTP options to use for communication, including authentication credentials.

protected HttpOptions $httpOptions

Methods

isSameOrigin()

Checks whether two absolute URIs have the same origin, i.e. the same scheme, host and port.

public static isSameOrigin(string $uri1, string $uri2) : bool

The comparison is case-insensitive and considers the default port of the scheme if the port is not given. IP addresses are compared by their binary value, so different notations of the same IPv6 address and the IPv4-mapped IPv6 notation of an IPv4 address are considered the same host.

Parameters
$uri1 : string
$uri2 : string
Return values
bool —

True if both URIs have the same origin. False if not, or if any of the URIs lacks scheme or host.

mayAuthenticate()

Checks whether the credentials may be sent with a request to the given URI.

public mayAuthenticate(string $uri) : bool

The credentials are bound to the origin (scheme, host and port) of the base URI of this HTTP client. For a request to a different origin, the auth_origin_callback of the HTTP options decides if configured, otherwise the credentials are not sent. Independent of the callback, credentials are never sent over plain HTTP if the base URI uses HTTPS.

Parameters
$uri : string

The target URI of the request. If relative, it is taken relative to the base URI.

Return values
bool —

True if the credentials may be sent with the request.

sendRequest()

Sends an HTTP request and returns a PSR-7 response.

public abstract sendRequest(string $method, string $uri[, array<string, mixed> $options = [] ]) : ResponseInterface
Parameters
$method : string

The request method (GET, PROPFIND, etc.)

$uri : string

The target URI. If relative, taken relative to the internal base URI of the HTTP client

$options : array<string, mixed> = []

Request-specific options, merged with/override the default options of the client. Supported options are:

  • 'allow_redirects' => boolean: True, if redirect responses should be resolved by the client.
  • 'body' => Request body as string: Optional body to send with the HTTP request
  • 'headers' => [ 'Headername' => 'Value' | [ 'Val1', 'Val2', ...] ]: Headers to include with the request
Tags
psalm-param

RequestOptions $options

throws
ClientExceptionInterface

if request could not be sent or response could not be parsed

RequestExceptionInterface

if request is not a well-formed HTTP request or is missing some critical piece of information (such as a Host or Method)

NetworkExceptionInterface

if the request cannot be sent due to a network failure of any kind, including a timeout

Return values
ResponseInterface —

The response retrieved from the server.

__construct()

Constructs a HttpClientAdapter object.

protected __construct(string $base_uri, HttpOptions $httpOptions) : mixed
Parameters
$base_uri : string

Base URI to be used when relative URIs are given to requests.

$httpOptions : HttpOptions

Credentials used to authenticate with the server.

checkCredentialsAvailable()

Checks if the needed credentials for an authentication scheme are available.

protected checkCredentialsAvailable(lowercase-string $scheme) : bool
Parameters
$scheme : lowercase-string

The authentication scheme to check for

Return values
bool —

True if the credentials needed for the scheme are available.

getOrigin()

Provides a normalized string representation of the origin of an absolute URI.

private static getOrigin(string $uri) : string|null

The result is a URL of the form scheme://host:port, with scheme and host in lowercase. If the URI does not contain a port, the default port of the scheme is used for http and https; for other schemes, the port is omitted. IP addresses are converted to their canonical notation, with IPv4-mapped IPv6 addresses converted to the IPv4 address.

Parameters
$uri : string
Return values
string|null —

The normalized origin, null if the URI lacks scheme or host.

On this page

Search results