AddressbookCollection
extends WebDavCollection
in package
Represents an addressbook collection on a WebDAV server.
Tags
Table of Contents
- PROPNAMES = [MStilkerichCardDavClientXmlElementsElementNames::DISPNAME, MStilkerichCardDavClientXmlElementsElementNames::GETCTAG, MStilkerichCardDavClientXmlElementsElementNames::SUPPORTED_ADDRDATA, MStilkerichCardDavClientXmlElementsElementNames::ABOOK_DESC, MStilkerichCardDavClientXmlElementsElementNames::MAX_RESSIZE]
- List of properties to query in refreshProperties() and returned by getProperties().
- $account : Account
- The CardDAV account this resource is associated/accessible with
- $uri : string
- URI of the resource
- $client : CardDavClient
- CardDavClient object for the account's base URI
- $props : array<string, mixed>
- Cached WebDAV properties of the resource
- __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
- Retrieves the getctag property for this addressbook collection (if supported by the server).
- getDetails() : string
- Provides the details for this addressbook as printable text.
- 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
= [MStilkerichCardDavClientXmlElementsElementNames::DISPNAME, MStilkerichCardDavClientXmlElementsElementNames::GETCTAG, MStilkerichCardDavClientXmlElementsElementNames::SUPPORTED_ADDRDATA, MStilkerichCardDavClientXmlElementsElementNames::ABOOK_DESC, MStilkerichCardDavClientXmlElementsElementNames::MAX_RESSIZE]
Tags
Properties
$account
The CardDAV account this resource is associated/accessible with
protected
Account
$account
$uri
URI of the resource
protected
string
$uri
$client
CardDavClient object for the account's base URI
private
CardDavClient
$client
$props
Cached WebDAV properties of the resource
private
array<string, mixed>
$props
= []
Tags
Methods
__construct()
Constructs a WebDavResource object.
public
__construct(string $uri, Account $account) : mixed
Parameters
- $uri : string
-
The target URI of the resource.
- $account : Account
-
The account by which the URI shall be accessed.
Return values
mixed —__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>
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
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
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.
- $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
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
Parameters
- $uri : string
-
The URI of the VCard to be deleted.
Return values
void —downloadResource()
Downloads the content of a given resource.
public
downloadResource(string $uri) : array<string, string>
Parameters
- $uri : string
-
URI of the requested resource.
Tags
Return values
array<string, string> —An associative array where the key 'body' maps to the content of the requested resource.
getAccount()
Returns the Account this resource belongs to.
public
getAccount() : Account
Return values
Account —getBasename()
Returns the basename (last path component) of the URI of this resource.
public
getBasename() : string
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>
Parameters
- $uri : string
-
URI of the address object to fetch
Tags
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>
Tags
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
Return values
string —The getctag property, or null if not provided by the server.
getDetails()
Provides the details for this addressbook as printable text.
public
getDetails() : 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 —getName()
Returns a displayname for the addressbook.
public
getName() : string
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
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
Return values
string —getUriPath()
Returns the path component of the URI of this resource.
public
getUriPath() : string
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) : array<string, array<string|int, mixed>>
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
-
Tell the server to return at most $limit results. 0 means no limit.
Tags
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)
refreshProperties()
Forces a refresh of the cached standard WebDAV properties for this resource.
public
refreshProperties() : void
Tags
Return values
void —supportsMultiGet()
Queries whether the server supports the addressbook-multiget REPORT on this addressbook collection.
public
supportsMultiGet() : bool
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
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
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 —Returns the ETag of the updated card if provided by the server, null otherwise. If null is returned, 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).
getNeededCollectionPropertyNames()
Provides the list of property names that should be requested upon call of refreshProperties().
protected
getNeededCollectionPropertyNames() : array<int, string>
Tags
Return values
array<int, string> —A list of property names including namespace prefix (e. g. '{DAV:}resourcetype').
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
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.