CardDAV Client Library

AddressbookCollection extends WebDavCollection
in package

Represents an addressbook collection on a WebDAV server.

Tags
psalm-import-type

SimpleConditions from Filter

ComplexConditions from Filter

psalm-type

VcardValidateResult = array{ level: int, message: string, node: \Sabre\VObject\Component | \Sabre\VObject\Property }

Table of Contents

Constants

PROPNAMES  : mixed = [\MStilkerich\CardDavClient\XmlElements\Element...
List of properties to query in refreshProperties() and returned by getProperties().

Properties

$account  : Account
The CardDAV account this resource is associated/accessible with
$uri  : string
URI of the resource

Methods

__construct()  : mixed
Constructs a WebDavResource object.
__toString()  : string
Provides a stringified representation of this addressbook (name and URI).
createCard()  : array<string, string>
Creates a new VCard in the addressbook.
createInstance()  : WebDavResource
Factory for WebDavResource objects.
deleteCard()  : void
Deletes a VCard from the addressbook.
downloadResource()  : array<string, string>
Downloads the content of a given resource.
getAccount()  : Account
Returns the Account this resource belongs to.
getBasename()  : string
Returns the basename (last path component) of the URI of this resource.
getCard()  : array<string, mixed>
Retrieves an address object from the addressbook collection and parses it to a VObject.
getChildren()  : array<int, WebDavResource>
Returns the child resources of this collection.
getClient()  : CardDavClient
Provides a CardDavClient object to interact with the server for this resource.
getCTag()  : string|null
Retrieves the getctag property for this addressbook collection (if supported by the server).
getDescription()  : string|null
Returns value of the CARDDAV:addressbook-description for the addressbook collection.
getDetails()  : string
Provides the details for this addressbook as printable text.
getDisplayName()  : string|null
Returns value of the DAV:displayname for the addressbook collection.
getName()  : string
Returns a displayname for the addressbook.
getSyncToken()  : string|null
Returns the sync token of this collection.
getUri()  : string
Returns the URI of this resource.
getUriPath()  : string
Returns the path component of the URI of this resource.
jsonSerialize()  : array<string, string>
Allows to serialize WebDavResource object to JSON.
query()  : array<string, array<string|int, mixed>>
Issues an addressbook-query report.
refreshProperties()  : void
Forces a refresh of the cached standard WebDAV properties for this resource.
supportsMultiGet()  : bool
Queries whether the server supports the addressbook-multiget REPORT on this addressbook collection.
supportsSyncCollection()  : bool
Queries whether the server supports the sync-collection REPORT on this collection.
updateCard()  : string|null
Updates an existing VCard of the addressbook.
getNeededCollectionPropertyNames()  : array<int, string>
Provides the list of property names that should be requested upon call of refreshProperties().
getProperties()  : array<string, mixed>
Returns the standard WebDAV properties for this resource.
shortenXmlNamespacesForPrinting()  : string
This function replaces some well-known XML namespaces with a long name with shorter names for printing.
supportsReport()  : bool
Checks if the server supports the given REPORT on this collection.
validateCard()  : void
Validates a VCard before sending it to a CardDAV server.

Constants

PROPNAMES

List of properties to query in refreshProperties() and returned by getProperties().

private mixed PROPNAMES = [\MStilkerich\CardDavClient\XmlElements\ElementNames::DISPNAME, \MStilkerich\CardDavClient\XmlElements\ElementNames::GETCTAG, \MStilkerich\CardDavClient\XmlElements\ElementNames::SUPPORTED_ADDRDATA, \MStilkerich\CardDavClient\XmlElements\ElementNames::ABOOK_DESC, \MStilkerich\CardDavClient\XmlElements\ElementNames::MAX_RESSIZE]
Tags
psalm-var

list

see
WebDavResource::getProperties()
WebDavResource::refreshProperties()

Properties

$account

The CardDAV account this resource is associated/accessible with

protected Account $account

Methods

__construct()

Constructs a WebDavResource object.

public __construct(string $uri, Account $account) : mixed
APIYes
Parameters
$uri : string

The target URI of the resource. The account's credentials are sent to the origin of this URI, see WebDavResource.

$account : Account

The account by which the URI shall be accessed.

__toString()

Provides a stringified representation of this addressbook (name and URI).

public __toString() : string

Note that the result of this function is meant for display, not parsing. Thus the content and formatting of the text may change without considering backwards compatibility.

Return values
string

createCard()

Creates a new VCard in the addressbook.

public createCard(VCard $vcard) : array<string, string>
APIYes

If the given VCard lacks the mandatory UID property, one will be generated. If the server provides an add-member URI, the new card will be POSTed to that URI. Otherwise, the function attempts to store the card to a URI whose last path component (filename) is derived from the UID of the VCard.

Parameters
$vcard : VCard

The VCard to be stored.

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.

createInstance()

Factory for WebDavResource objects.

public static createInstance(string $uri, Account $account[, null|array<int, string> $restype = null ]) : WebDavResource
APIYes

Given an account and URI, it attempts to create an instance of the most specific subclass matching the resource identified by the given URI. In case no resource can be accessed via the given account and URI, an exception is thrown.

Compared to direct construction of the object, creation via this factory involves querying the resourcetype of the URI with the server, so this is a checked form of instantiation whereas no server communication occurs when using the constructor.

Parameters
$uri : string

The target URI of the resource. The account's credentials are sent to the origin of this URI, see WebDavResource.

$account : Account

The account by which the URI shall be accessed.

$restype : null|array<int, string> = null

Array with the DAV:resourcetype properties of the URI (if already available saves the query)

Tags
psalm-param

null|list $restype

Return values
WebDavResource —

An object that is an instance of the most suited subclass of WebDavResource.

deleteCard()

Deletes a VCard from the addressbook.

public deleteCard(string $uri) : void
APIYes
Parameters
$uri : string

The URI of the VCard to be deleted.

downloadResource()

Downloads the content of a given resource.

public downloadResource(string $uri) : array<string, string>
APIYes

The account's credentials are only sent with the request if the given URI has the same origin as this resource, or the auth_origin_callback of the account permits it. Therefore, this method can be used to download resources from URIs of untrusted sources, such as photo URIs contained in VCards.

Parameters
$uri : string

URI of the requested resource. If relative, it is taken relative to the URI of this resource.

Tags
psalm-return

array{body: string}

Return values
array<string, string> —

An associative array where the key 'body' maps to the content of the requested resource.

getBasename()

Returns the basename (last path component) of the URI of this resource.

public getBasename() : string
APIYes
Return values
string

getCard()

Retrieves an address object from the addressbook collection and parses it to a VObject.

public getCard(string $uri) : array<string, mixed>
APIYes
Parameters
$uri : string

URI of the address object to fetch

Tags
psalm-return

array{vcard: VCard, etag: string, vcf: string}

Return values
array<string, mixed> —

Associative array with keys

  • etag(string): Entity tag of the returned card
  • vcf(string): VCard as string
  • vcard(VCard): VCard as Sabre/VObject VCard

getChildren()

Returns the child resources of this collection.

public getChildren() : array<int, WebDavResource>
APIYes

Only direct members of the collection are returned, i.e. resources with the same origin as the collection and the collection's path plus one path segment. Other resources reported by the server are ignored, so that the account's credentials are not sent to locations outside the collection.

Tags
psalm-return

list<WebDavResource>

Return values
array<int, WebDavResource> —

The children of this collection.

getClient()

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

public getClient() : CardDavClient

The base URL used by the returned client is the URL of this resource.

Return values
CardDavClient —

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

getCTag()

Retrieves the getctag property for this addressbook collection (if supported by the server).

public getCTag() : string|null
APIYes
Return values
string|null —

The getctag property, or null if not provided by the server.

getDescription()

Returns value of the CARDDAV:addressbook-description for the addressbook collection.

public getDescription() : string|null
APIYes
Return values
string|null —

CARDDAV:addressbook-description of the addressbook collection, null if not set.

getDetails()

Provides the details for this addressbook as printable text.

public getDetails() : string
APIYes

Note that the result of this function is meant for display, not parsing. Thus the content and formatting of the text may change without considering backwards compatibility.

Return values
string

getDisplayName()

Returns value of the DAV:displayname for the addressbook collection.

public getDisplayName() : string|null
APIYes
Return values
string|null —

DAV:displayname of the addressbook collection, null if not set.

getName()

Returns a displayname for the addressbook.

public getName() : string
APIYes

If a server-side displayname exists in the DAV:displayname property, it is returned. Otherwise, the last component of the URL is returned. This is suggested by RFC6352 to compose the addressbook name.

Return values
string —

Name of the addressbook

getSyncToken()

Returns the sync token of this collection.

public getSyncToken() : string|null
APIYes

Note that the value may be cached. If this resource was just created, this is not an issue, but if a property cache may exist for a longer time call WebDavResource::refreshProperties() first to ensure an up to date sync token is provided.

Return values
string|null —

The sync token, or null if the server does not provide a sync-token for this collection.

getUri()

Returns the URI of this resource.

public getUri() : string
APIYes
Return values
string

getUriPath()

Returns the path component of the URI of this resource.

public getUriPath() : string
APIYes
Return values
string

jsonSerialize()

Allows to serialize WebDavResource object to JSON.

public jsonSerialize() : array<string, string>
Return values
array<string, string> —

Associative array of attributes to serialize.

query()

Issues an addressbook-query report.

public query(array<string|int, mixed> $conditions[, array<int, string> $requestedVCardProps = [] ][, bool $matchAll = false ][, int $limit = 0 ]) : array<string, array<string|int, mixed>>
APIYes
Parameters
$conditions : array<string|int, mixed>

The query filter conditions, see Filter::__construct() for format.

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

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

$matchAll : bool = false

Whether all or any of the conditions needs to match.

$limit : int = 0

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

Tags
psalm-param

SimpleConditions|ComplexConditions $conditions

list $requestedVCardProps

psalm-return

array<string, array{vcard: VCard, etag: string}>

see
Filter
since
1.1.0
Return values
array<string, array<string|int, mixed>> —

Returns an array of matched VCards:

  • The keys of the array are the URIs of the vcards
  • The values are associative arrays with keys etag (type: string) and vcard (type: VCard)

supportsMultiGet()

Queries whether the server supports the addressbook-multiget REPORT on this addressbook collection.

public supportsMultiGet() : bool
APIYes
Return values
bool —

True if addressbook-multiget is supported for this collection.

supportsSyncCollection()

Queries whether the server supports the sync-collection REPORT on this collection.

public supportsSyncCollection() : bool
APIYes
Return values
bool —

True if sync-collection is supported for this collection.

updateCard()

Updates an existing VCard of the addressbook.

public updateCard(string $uri, VCard $vcard, string $etag) : string|null
APIYes

The update request to the server will be made conditional depending on that the provided ETag value of the card matches that on the server, meaning that the card has not been changed on the server in the meantime.

Parameters
$uri : string

The URI of the card to update.

$vcard : VCard

The updated VCard to be stored.

$etag : string

The ETag of the card that was originally retrieved and modified.

Return values
string|null —

On success, returns the ETag of the updated card if provided by the server, an empty string otherwise. In the latter case, it must be assumed that the server stored the card with modifications and the card should be read back from the server (this is a good idea anyway). In case of ETag precondition failure, null is returned. For other errors, an exception is thrown.

getProperties()

Returns the standard WebDAV properties for this resource.

protected getProperties() : array<string, mixed>

Retrieved from the server on first request, cached afterwards. Use WebDavResource::refreshProperties() to force update of cached properties.

Tags
psalm-return

PropTypes

Return values
array<string, mixed> —

Array mapping property name to corresponding value(s). The value type depends on the property.

shortenXmlNamespacesForPrinting()

This function replaces some well-known XML namespaces with a long name with shorter names for printing.

protected shortenXmlNamespacesForPrinting(string $s) : string
Parameters
$s : string

The fully-qualified XML element name (e.g. {urn:ietf:params:xml:ns:carddav}prop)

Return values
string —

The short name (e.g. {CARDDAV}prop)

supportsReport()

Checks if the server supports the given REPORT on this collection.

protected supportsReport(string $reportElement) : bool
Parameters
$reportElement : string

The XML element name of the REPORT of interest, including namespace (e.g. {DAV:}sync-collection).

Return values
bool —

True if the report is supported on this collection.

validateCard()

Validates a VCard before sending it to a CardDAV server.

protected validateCard(VCard $vcard) : void
Parameters
$vcard : VCard

The VCard to be validated.

Tags
throws
InvalidArgumentException

if the validation fails.

On this page

Search results