CardDAV Client Library

CardDavClient
in package

Implements the operations of the CardDAV protocol.

This class implements the lower level interactions with the CardDAV server that are utilized by the higher-level operations offered by the public entities (AddressbookCollection etc.) and services (Sync, Discovery.

An application interacting with the carddavclient library should not interact with this class directly, and it is considered an internal part of the library whose interfaces may change without being considered a change of the library's API.

Tags
psalm-import-type

HttpOptions from Account

RequestOptions from HttpClientAdapter

PropTypes from Prop

Table of Contents

Constants

MAP_NS2PREFIX  : mixed = [\MStilkerich\CardDavClient\XmlElements\Element...

Properties

$base_uri  : string
$httpClient  : HttpClientAdapter

Methods

__construct()  : mixed
absoluteUrl()  : string
compareUrlPaths()  : bool
concatUrl()  : string
createResource()  : array<string, string>
Requests the server to create the given resource.
deleteResource()  : void
Requests the server to delete the given resource.
findProperties()  : array<int, array<string, mixed>>
Retrieves a set of WebDAV properties for a resource.
findPropertiesWithLocation()  : array<string, mixed>
Retrieves a set of WebDAV properties for a resource, and provides the final request URI after redirects.
getAddressObject()  : array<string, string>
Fetches an address object.
getResource()  : ResponseInterface
isDirectMember()  : bool
Checks whether a URI identifies a direct member of a collection.
mayAuthenticate()  : bool
Checks whether the credentials of this client may be sent with a request to the given URI.
multiGet()  : Multistatus
Issues an addressbook-multiget request to the server.
query()  : Multistatus
Issues an addressbook-query report.
syncCollection()  : Multistatus
Requests a sync-collection REPORT from the CardDAV server.
updateResource()  : string|null
Requests the server to update the given resource.
addRequiredVCardProperties()  : array<int, string>
Adds required VCard properties to a set specified by the user.
assertHttpStatus()  : void
checkAndParseXMLMultistatus()  : Multistatus
determineReqCardProps()  : null|array<int, array<string, mixed>>
Builds a CARDDAV::address-data element with the requested properties.
getParserService()  : Service
getPathSegments()  : array<int, string>
Provides the percent-decoded, non-empty path segments of a URI.
requestWithRedirectionTarget()  : array<string, mixed>
Performs a WebDAV request, automatically following redirections and providing the final target with the result.

Constants

MAP_NS2PREFIX

private mixed MAP_NS2PREFIX = [\MStilkerich\CardDavClient\XmlElements\ElementNames::NSDAV => 'DAV', \MStilkerich\CardDavClient\XmlElements\ElementNames::NSCARDDAV => 'CARDDAV', \MStilkerich\CardDavClient\XmlElements\ElementNames::NSCS => 'CS']

Properties

Methods

__construct()

public __construct(string $base_uri, array<string|int, mixed> $httpOptions) : mixed
Parameters
$base_uri : string
$httpOptions : array<string|int, mixed>
Tags
psalm-param

HttpOptions $httpOptions

absoluteUrl()

public absoluteUrl(string $relurl) : string
Parameters
$relurl : string
Return values
string

compareUrlPaths()

public static compareUrlPaths(string $url1, string $url2) : bool
Parameters
$url1 : string
$url2 : string
Return values
bool

concatUrl()

public static concatUrl(string $baseurl, string $relurl) : string
Parameters
$baseurl : string
$relurl : string
Return values
string

createResource()

Requests the server to create the given resource.

public createResource(string $body, string $suggestedUri[, bool $post = false ]) : array<string, string>

On success, the actual URI of the new resource is contained in the returned array.

Parameters
$body : string

The content of the newly created resource.

$suggestedUri : string
  • If $post=false: The suggested new URI for the resource to create. If a resource by that name already exists, names will be derived from this URI by appending a numerical suffix for a limited number of retries.
  • If $post=true: The "Add-Member" URI to perform the POST request to. The server chooses the URI of the new resource.
$post : bool = false

If true, use a POST instead of a PUT request to create the resource (RFC 5995).

Tags
psalm-return

array{uri: string, etag: string}

Return values
array<string, string> —

Associative array with keys

  • uri (string): URI of the new resource if the request was successful
  • etag (string): Entity tag of the created resource if returned by server, otherwise empty string.

deleteResource()

Requests the server to delete the given resource.

public deleteResource(string $uri) : void
Parameters
$uri : string

findProperties()

Retrieves a set of WebDAV properties for a resource.

public findProperties(string $uri, array<int, string> $props[, string $depth = "0" ]) : array<int, array<string, mixed>>
Parameters
$uri : string

The URI of the resource to retrieve properties for.

$props : array<int, string>

List of properties to retrieve, given as XML element names

$depth : string = "0"

Value for the Depth header

Tags
psalm-param

list $props

"0"|"1"|"infinity" $depth

psalm-return

list<array{uri: string, props: PropTypes}>

Return values
array<int, array<string, mixed>>

findPropertiesWithLocation()

Retrieves a set of WebDAV properties for a resource, and provides the final request URI after redirects.

public findPropertiesWithLocation(string $uri, array<int, string> $props[, string $depth = "0" ]) : array<string, mixed>
Parameters
$uri : string

The URI of the resource to retrieve properties for.

$props : array<int, string>

List of properties to retrieve, given as XML element names

$depth : string = "0"

Value for the Depth header

Tags
psalm-param

list $props

"0"|"1"|"infinity" $depth

psalm-return

array{location: string, results: list<array{uri: string, props: PropTypes}>}

Return values
array<string, mixed> —

Associative array with keys

  • location (string): Absolute URI of the resource after following redirects
  • results (array): The retrieved properties as returned by CardDavClient::findProperties()

getAddressObject()

Fetches an address object.

public getAddressObject(string $uri) : array<string, string>
Parameters
$uri : string

URI of the address object to fetch

Tags
psalm-return

array{etag: string, vcf: string}

Return values
array<string, string> —

Associative array with keys

  • etag (string): Entity tag of the created resource if returned by server, otherwise empty string.
  • vcf (string): The address data of the address object

getResource()

public getResource(string $uri) : ResponseInterface
Parameters
$uri : string
Return values
ResponseInterface

isDirectMember()

Checks whether a URI identifies a direct member of a collection.

public static isDirectMember(string $collectionUri, string $memberUri) : bool

A direct (internal) member of a collection has the same origin as the collection, and its path consists of the path of the collection plus one additional path segment (RFC 4918, section 5.2). Path segments are compared after percent-decoding them, and empty path segments (e.g. from trailing slashes) are ignored.

Parameters
$collectionUri : string

The absolute URI of the collection

$memberUri : string

The absolute URI to check

Return values
bool —

True if $memberUri identifies a direct member of the collection identified by $collectionUri

mayAuthenticate()

Checks whether the credentials of this client may be sent with a request to the given URI.

public mayAuthenticate(string $uri) : bool
Parameters
$uri : string
Tags
see
HttpClientAdapter::mayAuthenticate()
Return values
bool

multiGet()

Issues an addressbook-multiget request to the server.

public multiGet(string $addressbookUri, array<int, string> $requestedUris[, array<int, string> $requestedVCardProps = [] ]) : Multistatus
Parameters
$addressbookUri : string

URI of the addressbook to fetch the objects from

$requestedUris : array<int, string>

List of URIs of the objects to fetch

$requestedVCardProps : array<int, string> = []

List of VCard properties to request, empty to request the full cards.

Tags
psalm-param

list $requestedUris

list $requestedVCardProps

psalm-return

Multistatus<XmlElements\ResponsePropstat>

Return values
Multistatus

query()

Issues an addressbook-query report.

public query(string $addressbookUri, Filter $filter, array<int, string> $requestedVCardProps, int $limit) : Multistatus
Parameters
$addressbookUri : string

The URI of the addressbook collection to query

$filter : Filter

The query filter conditions

$requestedVCardProps : array<int, string>

A list of the requested VCard properties. If empty array, the full VCards are requested from the server.

$limit : int

Tell the server to return at most $limit results. 0 means no limit.

Tags
psalm-param

list $requestedVCardProps

psalm-return

Multistatus

Return values
Multistatus

syncCollection()

Requests a sync-collection REPORT from the CardDAV server.

public syncCollection(string $addressbookUri, string $syncToken) : Multistatus

Note: Google's server does not accept an empty syncToken, though explicitly allowed for initial sync by RFC6578. It will respond with 400 Bad Request and error message "Request contains an invalid argument."

The Google issues have been reported to Google: https://issuetracker.google.com/issues/160190530

Parameters
$addressbookUri : string
$syncToken : string
Return values
Multistatus

updateResource()

Requests the server to update the given resource.

public updateResource(string $body, string $uri[, string $etag = "" ]) : string|null

Normally, the ETag of the existing expected server-side resource should be given to make the update conditional on that no other changes have been done to the server-side resource, otherwise lost updates might occur. However, if no ETag is given, the server-side resource is overwritten unconditionally.

Parameters
$body : string
$uri : string
$etag : string = ""
Return values
string|null —

ETag of the updated resource, an empty string if no ETag was given by the server, or null if the update failed because the server-side ETag did not match the given one.

addRequiredVCardProperties()

Adds required VCard properties to a set specified by the user.

private static addRequiredVCardProperties(array<int, string> $requestedVCardProps) : array<int, string>

This is needed to ensure retrieval of a valid VCard, as some properties are mandatory.

Parameters
$requestedVCardProps : array<int, string>

List of properties requested by the user

Tags
psalm-param

list $requestedVCardProps

psalm-return

list

Return values
array<int, string> —

List of properties requested by the user, completed with mandatory properties.

assertHttpStatus()

private static assertHttpStatus(ResponseInterface $davReply, int $minCode, int $maxCode, string $nfo) : void
Parameters
$davReply : ResponseInterface
$minCode : int
$maxCode : int
$nfo : string

checkAndParseXMLMultistatus()

private static checkAndParseXMLMultistatus(ResponseInterface $davReply[, string $responseType = Response::class ]) : Multistatus
Parameters
$davReply : ResponseInterface
$responseType : string = Response::class
Tags
template
psalm-param

class-string<RT> $responseType

psalm-return

Multistatus<RT>

Return values
Multistatus

determineReqCardProps()

Builds a CARDDAV::address-data element with the requested properties.

private determineReqCardProps(array<int, string> $requestedVCardProps) : null|array<int, array<string, mixed>>

If no properties are requested, returns null - an empty address-data element means that the full VCards shall be returned.

Some properties that are mandatory are added to the list.

Parameters
$requestedVCardProps : array<int, string>

List of the VCard properties requested by the user

Tags
psalm-param

list $requestedVCardProps

psalm-return

null|list<array{name: string, attributes: array{name: string}}>

Return values
null|array<int, array<string, mixed>>

getParserService()

private static getParserService() : Service
Return values
Service

getPathSegments()

Provides the percent-decoded, non-empty path segments of a URI.

private static getPathSegments(string $uri) : array<int, string>
Parameters
$uri : string
Return values
array<int, string>

requestWithRedirectionTarget()

Performs a WebDAV request, automatically following redirections and providing the final target with the result.

private requestWithRedirectionTarget(string $method, string $uri[, RequestOptions $options = [] ]) : array<string, mixed>
Parameters
$method : string

The WebDAV method of the request (PROPFIND, REPORT, etc.)

$uri : string

The target of the request

$options : RequestOptions = []

Additional options for the request

Tags
psalm-return

array{redirected: bool, location: string, response: Psr7Response}

Return values
array<string, mixed>
On this page

Search results