CardDAV Client Library

Account
in package
implements JsonSerializable

Represents an account on a CardDAV Server.

Tags
psalm-import-type

Credentials from HttpClientAdapter

Interfaces, Classes and Traits

JsonSerializable

Table of Contents

$baseUrl  : string|null
URL of the discovered CardDAV server, with empty path. May be null if not discovered yet.
$credentials  : Credentials
The credentials for authentication, null to disable authentication.
$discoveryUri  : string
URI originally used to discover the account.
__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.
findAddressbookHome()  : string|null
Queries the given URI for the CARDDAV:addressbook-home-set property.
findCurrentUserPrincipal()  : string|null
Queries the given URI for the current-user-principal property.
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, ?string>
Allows to serialize an Account object to JSON.
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

$credentials

The credentials for authentication, null to disable authentication.

private Credentials $credentials

$discoveryUri

URI originally used to discover the account.

private string $discoveryUri

Example: example.com

Methods

__construct()

Construct a new Account object.

public __construct(string $discoveryUri, string|array<string|int, mixed> $credentials[, string $password = "" ][, string $baseUrl = null ]) : mixed
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).

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

The credentials to use for authentication. 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)

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 $credentials parameter. This parameter is ignored unless $credentials 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|Credentials $credentials

Return values
mixed —

__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, ?string> $props) : Account

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

Parameters
$props : array<string, ?string>

An associative array containing the Account attributes. Keys: discoveryUri, username, password, baseUrl with the meaning from Account::__construct()

Tags
see
Account::jsonSerialize()
Return values
Account —

findAddressbookHome()

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

public findAddressbookHome(string $principalUri) : string|null

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).

Tags
todo

Per RFC6352 several home locations could be returned, but we currently only use one. However, it is rather unlikely that there would be several addressbook home locations.

Return values
string|null —

The user's addressbook home 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).

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).

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
Return values
string —

getUrl()

Returns the base URL of the CardDAV service.

public getUrl() : string
Return values
string —

jsonSerialize()

Allows to serialize an Account object to JSON.

public jsonSerialize() : array<string, ?string>
Tags
see
Account::constructFromArray()
Return values
array<string, ?string> —

Associative array of attributes to serialize.

setUrl()

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

public setUrl(string $url) : void
Parameters
$url : string
Return values
void —

Search results