CardDAV Client Library

Discovery
in package

Provides a service to discover the addressbooks for a CardDAV account.

It implements the discovery using the mechanisms specified in RFC 6764, which is based on DNS SRV/TXT records and/or well-known URI redirection on the server.

Tags
psalm-type

Server = array{ host: string, port: string, scheme: string, dnsrr?: string, userinput?: bool }

SrvRecord = array{pri: int, weight: int, target: string, port: int}

TxtRecord = array{txt: string}

Table of Contents

Constants

KNOWN_SERVERS  : array<string, string> = ["gmail.com" => "www.googleapis.com", "googlema...
Some builtins for public providers that don't have discovery properly set up.

Methods

discoverAddressbooks()  : array<int, AddressbookCollection>
Discover the addressbooks for a CardDAV account.
dnsGetRecord()  : array<string|int, mixed>|false
Queries DNS resource records.
discoverContextPath()  : array<string|int, string>
Provides a list of URIs to check for discovering the location of the CardDAV service.
discoverServers()  : array<string|int, mixed>
Discovers the CardDAV service for the given domain using DNS SRV lookups.
discoverWithinDomainPolicy()  : array<int, AddressbookCollection>
Performs the discovery steps for discoverAddressbooks().
isIpAddress()  : bool
Checks whether the host part of a URI is an IP address.
isWithinDomain()  : bool
Checks whether a URI points to a server within the domain used for discovery.
parseDiscoveryUri()  : array<string|int, mixed>
Parses the discovery URI of an account.
sortSrvRecords()  : array<string|int, mixed>
Orders DNS SRV records by preference according to RFC 2782.
tryContextPath()  : null|array<int, AddressbookCollection>
Attempts to discover the addressbook home and addressbooks for a given context path.

Constants

KNOWN_SERVERS

Some builtins for public providers that don't have discovery properly set up.

private array<string, string> KNOWN_SERVERS = ["gmail.com" => "www.googleapis.com", "googlemail.com" => "www.googleapis.com"]

It maps a domain name that is part of the typically used usernames to a working discovery URI. This allows discovery from data as typically provided by a user without the application having to care about it.

Methods

discoverAddressbooks()

Discover the addressbooks for a CardDAV account.

public discoverAddressbooks(Account $account) : array<int, AddressbookCollection>
APIYes

The discovery may involve several servers, found via DNS SRV records, redirects or the URLs reported by the servers. If the discovery URI contains an IP address, no DNS lookups are performed; only the path given in the discovery URI and the well-known URI are tried on that server. The account's credentials are only sent to some of the servers:

  • The discovery domain is the host given in the discovery URI of the account. Credentials are sent to servers within the discovery domain, i.e. the domain itself or any of its subdomains, if they use HTTPS (or HTTP, if HTTP was explicitly requested in the discovery URI). If the discovery URI contains an IP address, only that IP address is considered to be within the discovery domain. Any port is accepted.
  • For other servers, the auth_origin_callback of the account (see Account::__construct()) decides. Without a callback, the credentials are not sent to them, and such servers will typically not be usable for the discovery.
  • Servers found via DNS SRV records are used if they are within the discovery domain. For servers outside the discovery domain (e.g. a custom domain hosted by a provider), RFC 6764 recommends that the user confirms that the server is suitable. If the account has an auth_origin_callback, the callback is asked ($targetUri is the server's URL, $baseUri the URL of the discovery domain) and the server is used only if it returns true. Without a callback, such servers are used for compatibility with earlier versions of this library.

The rules above only apply during discovery. Afterwards, the auth_origin_callback of the account is the same as before, also for the discovered addressbooks.

Parameters
$account : Account

The CardDAV account providing credentials and initial discovery URI.

Tags
psalm-return

list<AddressbookCollection>

throws
Exception

In case of error, sub-classes of \Exception are thrown, with an error message contained within the \Exception object.

Return values
array<int, AddressbookCollection> —

The discovered addressbooks.

dnsGetRecord()

Queries DNS resource records.

protected dnsGetRecord(string $hostname, int $type) : array<string|int, mixed>|false

This is a wrapper for dns_get_record() that allows to replace the DNS lookups in tests.

Parameters
$hostname : string

The DNS name to query

$type : int

The type of the resource records to query (DNS_SRV, DNS_TXT)

Return values
array<string|int, mixed>|false —

The resource records as returned by dns_get_record(), false on error

discoverContextPath()

Provides a list of URIs to check for discovering the location of the CardDAV service.

private discoverContextPath(array<string|int, mixed> $server) : array<string|int, string>

The provided context paths comprise both well-known URIs as well as paths discovered via DNS TXT records. DNS TXT lookup is only performed for servers that have themselves been discovery using DNS SRV lookups, using the same service resource record.

Parameters
$server : array<string|int, mixed>

A server record (associative array) as returned by discoverServers()

Tags
psalm-param

Server $server

psalm-return

list

see
Discovery::discoverServers()
Return values
array<string|int, string> —

The context paths that should be tried for discovery in the provided order.

discoverServers()

Discovers the CardDAV service for the given domain using DNS SRV lookups.

private discoverServers(string $host, bool $force_ssl) : array<string|int, mixed>
Parameters
$host : string

A domain name to discover the service for

$force_ssl : bool

If true, only services with transport encryption (carddavs) will be discovered, otherwise the function will try to discover unencrypted (carddav) services after failing to discover encrypted ones.

Tags
psalm-return

list<Server>

Return values
array<string|int, mixed> —

Returns an array of associative arrays of services discovered via DNS. If nothing was found, the returned array is empty.

discoverWithinDomainPolicy()

Performs the discovery steps for discoverAddressbooks().

private discoverWithinDomainPolicy(Account $account, string $protocol, string $host, string $port, string $path, bool $force_ssl, callable|null $appCallback) : array<int, AddressbookCollection>

The account's auth_origin_callback must be set to the discovery policy when calling this function.

Parameters
$account : Account

The account to discover the addressbooks for

$protocol : string

The protocol of the discovery URI (http or https)

$host : string

The host of the discovery URI (the discovery domain)

$port : string

The port of the discovery URI

$path : string

The path of the discovery URI

$force_ssl : bool

Whether only HTTPS shall be used

$appCallback : callable|null

The auth_origin_callback provided by the application

Tags
psalm-param

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

psalm-return

list<AddressbookCollection>

Return values
array<int, AddressbookCollection> —

The discovered addressbooks.

isIpAddress()

Checks whether the host part of a URI is an IP address.

private static isIpAddress(string $host) : bool
Parameters
$host : string

The host part of a URI, IPv6 addresses enclosed in brackets

Return values
bool

isWithinDomain()

Checks whether a URI points to a server within the domain used for discovery.

private static isWithinDomain(string $uri, string $domain, string $protocol) : bool

The host of the URI must be the domain itself or one of its subdomains. The URI must use HTTPS, or HTTP if the discovery was explicitly requested using HTTP. If the discovery domain is an IP address, only that IP address is considered to be within the domain. In both cases, any port is accepted.

Parameters
$uri : string

The absolute URI to check

$domain : string

The domain (or IP address) of the discovery URI

$protocol : string

The protocol of the discovery URI (http or https)

Return values
bool

parseDiscoveryUri()

Parses the discovery URI of an account.

private static parseDiscoveryUri(string $uri) : array<string|int, mixed>

The discovery URI may lack the scheme, in which case https is used. If it lacks the port, the default port of the scheme is used. If it lacks the path, / is used.

Parameters
$uri : string

The discovery URI

Tags
psalm-return

array{string, string, string, string}

throws
InvalidArgumentException

If the URI lacks a host, has a scheme other than http/https, or contains user information

Return values
array<string|int, mixed> —

The protocol (http or https), host (lowercase, IPv6 address in brackets), port and path of the discovery URI. A query or fragment is dropped.

sortSrvRecords()

Orders DNS SRV records by preference according to RFC 2782.

private static sortSrvRecords(array<string|int, mixed> $records) : array<string|int, mixed>

Records are sorted by ascending priority, as lower priority values are preferred. Records with the same priority are sorted by descending weight. RFC 2782 actually requires a weighted random selection among records with the same priority; ordering by descending weight is a deterministic approximation that prefers the targets the server administrator assigned the largest share of the load to.

Parameters
$records : array<string|int, mixed>

The SRV records as returned by dns_get_record()

Tags
psalm-param

list<SrvRecord> $records

psalm-return

list<SrvRecord>

Return values
array<string|int, mixed> —

The SRV records in the order they should be tried.

tryContextPath()

Attempts to discover the addressbook home and addressbooks for a given context path.

private tryContextPath(Account $account, string $contextpath) : null|array<int, AddressbookCollection>
Parameters
$account : Account

The CardDAV account

$contextpath : string

The context URI to try as starting point of the discovery

Tags
psalm-return

null|list<AddressbookCollection>

Return values
null|array<int, AddressbookCollection> —

The discovered addressbooks.

On this page

Search results