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
Table of Contents
- MAP_NS2PREFIX = [MStilkerichCardDavClientXmlElementsElementNames::NSDAV => 'DAV', MStilkerichCardDavClientXmlElementsElementNames::NSCARDDAV => 'CARDDAV', MStilkerichCardDavClientXmlElementsElementNames::NSCS => 'CS']
- $base_uri : string
- $httpClient : HttpClientAdapter
- __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.
- getAddressObject() : array<string, string>
- Fetches an address object.
- getResource() : ResponseInterface
- 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
- 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
= [MStilkerichCardDavClientXmlElementsElementNames::NSDAV => 'DAV', MStilkerichCardDavClientXmlElementsElementNames::NSCARDDAV => 'CARDDAV', MStilkerichCardDavClientXmlElementsElementNames::NSCS => 'CS']
Properties
$base_uri
protected
string
$base_uri
$httpClient
protected
HttpClientAdapter
$httpClient
Methods
__construct()
public
__construct(string $base_uri, array<string|int, mixed> $credentials) : mixed
Parameters
- $base_uri : string
- $credentials : array<string|int, mixed>
Tags
Return values
mixed —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>
Parameters
- $body : string
- $suggestedUri : string
- $post : bool = false
-
If true
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.
deleteResource()
Requests the server to delete the given resource.
public
deleteResource(string $uri) : void
Parameters
- $uri : string
Return values
void —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
Return values
array<int, array<string, mixed>> —getAddressObject()
Fetches an address object.
public
getAddressObject(string $uri) : array<string, string>
Parameters
- $uri : string
-
URI of the address object to fetch
Tags
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 —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
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
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
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
Return values
void —checkAndParseXMLMultistatus()
private
static checkAndParseXMLMultistatus(ResponseInterface $davReply[, string $responseType = XmlElementsResponse::class ]) : Multistatus
Parameters
- $davReply : ResponseInterface
- $responseType : string = XmlElementsResponse::class
Tags
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
Return values
null|array<int, array<string, mixed>> —getParserService()
private
static getParserService() : Service
Return values
Service —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