CardDAV Client Library

Account
in package
implements JsonSerializable

Represents an account on a CardDAV Server.

Tags
psalm-type

HttpOptions = array{ username?: string, password?: string, bearertoken?: string, verify?: bool|string, ssl_key?: string | non-empty-list, cert?: string | non-empty-list, preemptive_basic_auth?: bool, query?: array<string, string>, headers?: array<string, string | list>, auth_origin_callback?: callable(string, string): bool, }

SerializedAccount = HttpOptions & array{discoveryUri: string, baseUrl?: ?string}

Table of Contents

Interfaces

JsonSerializable

Properties

$baseUrl  : string|null
URL of the discovered CardDAV server, with empty path. May be null if not discovered yet.
$discoveryUri  : string
URI originally used to discover the account.
$httpOptions  : HttpOptions
Options for the HTTP communication, including authentication credentials.

Methods

__construct()  : mixed
Construct a new Account object.
__toString()  : string
Provides a readable form of the core properties of the Account.
constructFromArray()  : Account
Constructs an Account object from an array representation.
findAddressbookHomes()  : null|array<int, string>
Queries the given URI for the CARDDAV:addressbook-home-set property.
findCurrentUserPrincipal()  : string|null
Queries the given URI for the current-user-principal property.
getAuthOriginCallback()  : callable|null
Returns the callback that decides whether the credentials may be sent to a different origin, if any.
getClient()  : CardDavClient
Provides a CardDavClient object to interact with the server for this account.
getDiscoveryUri()  : string
Returns the discovery URI for this Account.
getUrl()  : string
Returns the base URL of the CardDAV service.
jsonSerialize()  : array<string|int, mixed>
Allows to serialize an Account object to JSON.
setAuthOriginCallback()  : void
Sets the callback that decides whether the credentials may be sent to a different origin.
setUrl()  : void
Set the base URL of this account once the service URL has been discovered.

Properties

$baseUrl

URL of the discovered CardDAV server, with empty path. May be null if not discovered yet.

private string|null $baseUrl

Example: https://carddav.example.com:443

$discoveryUri

URI originally used to discover the account.

private string $discoveryUri

Example: example.com

$httpOptions

Options for the HTTP communication, including authentication credentials.

private HttpOptions $httpOptions

Methods

__construct()

Construct a new Account object.

public __construct(string $discoveryUri, string|array<string|int, mixed> $httpOptions[, string $password = "" ][, string $baseUrl = null ]) : mixed
APIYes
Parameters
$discoveryUri : string

The URI to use for service discovery. This can be a partial URI, in the simplest case just a domain name. Note that if no protocol is given, https will be used. Unencrypted HTTP will only be done if explicitly given (e.g. http://example.com).

$httpOptions : string|array<string|int, mixed>

The options for HTTP communication, including authentication credentials. An array with any of the keys (if no password is needed, the array may be empty, e.g. GSSAPI/Kerberos):

  • username/password: The username and password for mechanisms requiring such credentials (e.g. Basic, Digest)
  • bearertoken: The token to use for Bearer authentication (OAUTH2)
  • verify: How to verify the server-side HTTPS certificate. True (the default) enables certificate verification against the default CA bundle of the OS, false disables certificate verification (note that this defeats the purpose of HTTPS and opens the door for man in the middle attacks). Set to the path of a PEM file containing a custom CA bundle to perform verification against a custom set of certification authorities.
  • ssl_key: The path to the private key to use for mututal TLS verification, cannot be used with disabled verification, Guzzle will accept an array as well as a string, with the first element of the array being the filepath and the second being the password
  • cert: The path to the PEM formatted client side certificate (password can be specified analog to ssl_key)
  • preemptive_basic_auth: Set to true to always submit an Authorization header for HTTP Basic authentication (username and password options also required in this case) even if not challenged by the server. This may be required in rare use cases where the server allows unauthenticated access and will not challenge the client.
  • query: Query options to append to every URL queried for this account, as an associative array of query options and values.
  • headers: Headers to add to each request sent for this account, an associative array mapping header name to header value (string) or header values (list). Note that these headers are sent with all requests, including requests to other origins than that of the CardDAV server (e.g. after redirects), with the exception of Authorization and Cookie headers, which the HTTP client library removes on redirects to other origins. Do not use this option to pass credentials, use the username/password or bearertoken options instead.
  • auth_origin_callback: The credentials are only sent to the origin (scheme, host and port) of the URL of the resource the request is made for (or the base URL of this Account for requests not related to a specific resource). A callback function function (string $targetUri, string $baseUri): bool can be given to decide whether the credentials may be sent with a request to a different origin, e.g. after a redirect. $targetUri is the URI of the request, $baseUri the URI the credentials are bound to. Return true to send the credentials to $targetUri. The callback is not consulted for redirects that are followed by the HTTP client library automatically; credentials are never sent to a different origin for those. Credentials are never sent over plain HTTP if $baseUri uses HTTPS, regardless of the callback. Note that this option is not included in the serialized form of the Account (Account::jsonSerialize()) and must be set again after reconstructing the Account, e.g. using Account::setAuthOriginCallback(). During discovery, the callback is also consulted for servers outside the discovery domain, see Discovery::discoverAddressbooks().

Deprecated: username as string for authentication mechanisms requiring username / password.

$password : string = ""

Deprecated: The password to use for authentication. This parameter is deprecated, include the password in the $httpOptions parameter. This parameter is ignored unless $httpOptions is used in its deprecated string form.

$baseUrl : string = null

The URL of the CardDAV server without the path part (e.g. https://carddav.example.com:443). This URL is used as base URL for the underlying CardDavClient that can be retrieved using Account::getClient(). When relative URIs are passed to the client, they will be relative to this base URL. If this account is used for discovery with the Discovery service, this parameter can be omitted.

Tags
psalm-param

string|HttpOptions $httpOptions

__toString()

Provides a readable form of the core properties of the Account.

public __toString() : string

This is meant for printing to a human, not for parsing, and therefore may change without considering this a backwards incompatible change.

Return values
string

constructFromArray()

Constructs an Account object from an array representation.

public static constructFromArray(array<string|int, mixed> $props) : Account
APIYes

This can be used to reconstruct/deserialize an Account from a stored (JSON) representation.

Parameters
$props : array<string|int, mixed>
Tags
psalm-param

SerializedAccount $props

see
Account::jsonSerialize()
Return values
Account

findAddressbookHomes()

Queries the given URI for the CARDDAV:addressbook-home-set property.

public findAddressbookHomes(string $principalUri) : null|array<int, string>

Property description by RFC6352: The CARDDAV:addressbook-home-set property is meant to allow users to easily find the address book collections owned by the principal. Typically, users will group all the address book collections that they own under a common collection. This property specifies the URL of collections that are either address book collections or ordinary collections that have child or descendant address book collections owned by the principal.

Parameters
$principalUri : string

The given URI should be (one of) the authenticated user's principal URI(s).

Return values
null|array<int, string> —

The user's addressbook home URIs, or null in case of error. The returned URIs are suited to be used for queries with this client (i.e. either a full URI, or meaningful as relative URI to the base URI of this client).

findCurrentUserPrincipal()

Queries the given URI for the current-user-principal property.

public findCurrentUserPrincipal(string $contextPathUri) : string|null

Property description by RFC5397: The DAV:current-user-principal property contains either a DAV:href or DAV:unauthenticated XML element. The DAV:href element contains a URL to a principal resource corresponding to the currently authenticated user. That URL MUST be one of the URLs in the DAV:principal-URL or DAV:alternate-URI-set properties defined on the principal resource and MUST be an http(s) scheme URL. When authentication has not been done or has failed, this property MUST contain the DAV:unauthenticated pseudo-principal. In some cases, there may be multiple principal resources corresponding to the same authenticated principal. In that case, the server is free to choose any one of the principal resource URIs for the value of the DAV:current-user-principal property. However, servers SHOULD be consistent and use the same principal resource URI for each authenticated principal.

Parameters
$contextPathUri : string

The given URI should typically be a context path per the terminology of RFC6764.

Return values
string|null —

The principal URI (string), or NULL in case of error. The returned URI is suited to be used for queries with this client (i.e. either a full URI, or meaningful as relative URI to the base URI of this client).

getAuthOriginCallback()

Returns the callback that decides whether the credentials may be sent to a different origin, if any.

public getAuthOriginCallback() : callable|null
APIYes
Tags
psalm-return

null|callable(string, string): bool

see
Account::setAuthOriginCallback()
Return values
callable|null

getClient()

Provides a CardDavClient object to interact with the server for this account.

public getClient([string $baseUrl = null ]) : CardDavClient
Parameters
$baseUrl : string = null

A base URL to use by the client to resolve relative URIs. If not given, the base url of the Account is used. This is useful, for example, to override the base path with that of a collection.

Return values
CardDavClient —

A CardDavClient object to interact with the server for this account.

getDiscoveryUri()

Returns the discovery URI for this Account.

public getDiscoveryUri() : string
APIYes
Return values
string

getUrl()

Returns the base URL of the CardDAV service.

public getUrl() : string
APIYes
Return values
string

jsonSerialize()

Allows to serialize an Account object to JSON.

public jsonSerialize() : array<string|int, mixed>
Tags
psalm-return

SerializedAccount

@return

array<string, ?string|bool> Associative array of attributes to serialize.

see
Account::constructFromArray()
Return values
array<string|int, mixed>

setAuthOriginCallback()

Sets the callback that decides whether the credentials may be sent to a different origin.

public setAuthOriginCallback(callable|null $callback) : void
APIYes

This is equivalent to the auth_origin_callback HTTP option (see Account::__construct()). As the callback is not included in the serialized form of the Account, this method can be used to set it again after reconstructing an Account using Account::constructFromArray(). The callback applies to all requests made for this account, including those for resources created before setting the callback.

Parameters
$callback : callable|null

The callback, or null to remove the callback.

Tags
psalm-param

null|callable(string, string): bool $callback

setUrl()

Set the base URL of this account once the service URL has been discovered.

public setUrl(string $url) : void
Parameters
$url : string
On this page

Search results