CardDAV Client Library

HttpClientAdapter
in package

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-type

Credentials = array{ username?: string, password?: string, bearertoken?: string }

Table of Contents

NEEDED_AUTHNFO  = ['basic' => ['username', 'password'], 'digest' => ['username', 'password'], 'bearer' => ['bearertoken']]
Defines which credential attributes are required for auth mechanisms.
$baseUri  : string
The base URI for requests.
$credentials  : Credentials
The credentials to use for authentication
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.
checkSameDomainAsBase()  : bool
Checks whether the given URI has the same domain as the base URI of this HTTP client.
getDomainFromSubdomain()  : string
Extracts the domain name from a subdomain.

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

$credentials

The credentials to use for authentication

protected Credentials $credentials

Methods

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

throws
RequestExceptionInterface

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

throws
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, Credentials $credentials) : mixed
Parameters
$base_uri : string

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

$credentials : Credentials

Credentials used to authenticate with the server.

Return values
mixed —

checkCredentialsAvailable()

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

protected checkCredentialsAvailable(string $scheme) : bool
Parameters
$scheme : string
Return values
bool —

True if the credentials needed for the scheme are available.

checkSameDomainAsBase()

Checks whether the given URI has the same domain as the base URI of this HTTP client.

protected checkSameDomainAsBase(string $uri) : bool

If the given URI does not contain a domain part, true is returned (as when used, it will get that part from the base URI).

Parameters
$uri : string

The URI to check

Return values
bool —

True if the URI shares the same domain as the base URI.

getDomainFromSubdomain()

Extracts the domain name from a subdomain.

protected static getDomainFromSubdomain(string $subdomain) : string

If the given string does not have a subdomain (i.e. top-level domain or domain only), it is returned as provided.

Parameters
$subdomain : string

The subdomain (e.g. sub.example.com)

Return values
string —

The domain of $subdomain (e.g. example.com)

Search results