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
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>
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
(
$targetUriis the server's URL,$baseUrithe 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
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
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
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
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
boolisWithinDomain()
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
boolparseDiscoveryUri()
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
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
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
Return values
null|array<int, AddressbookCollection> —The discovered addressbooks.