Account
in package
implements
JsonSerializable
Represents an account on a CardDAV Server.
Tags
Table of Contents
Interfaces
- JsonSerializable
Properties
- $baseUrl : string|null
- URL of the discovered CardDAV server, with empty path. May be null if not discovered yet.
- $discoveryUri : string
- URI originally used to discover the account.
- $httpOptions : HttpOptions
- Options for the HTTP communication, including authentication credentials.
Methods
- __construct() : mixed
- Construct a new Account object.
- __toString() : string
- Provides a readable form of the core properties of the Account.
- constructFromArray() : Account
- Constructs an Account object from an array representation.
- findAddressbookHomes() : null|array<int, string>
- Queries the given URI for the CARDDAV:addressbook-home-set property.
- findCurrentUserPrincipal() : string|null
- Queries the given URI for the current-user-principal property.
- getAuthOriginCallback() : callable|null
- Returns the callback that decides whether the credentials may be sent to a different origin, if any.
- getClient() : CardDavClient
- Provides a CardDavClient object to interact with the server for this account.
- getDiscoveryUri() : string
- Returns the discovery URI for this Account.
- getUrl() : string
- Returns the base URL of the CardDAV service.
- jsonSerialize() : array<string|int, mixed>
- Allows to serialize an Account object to JSON.
- setAuthOriginCallback() : void
- Sets the callback that decides whether the credentials may be sent to a different origin.
- setUrl() : void
- Set the base URL of this account once the service URL has been discovered.
Properties
$baseUrl
URL of the discovered CardDAV server, with empty path. May be null if not discovered yet.
private
string|null
$baseUrl
Example: https://carddav.example.com:443
$discoveryUri
URI originally used to discover the account.
private
string
$discoveryUri
Example: example.com
$httpOptions
Options for the HTTP communication, including authentication credentials.
private
HttpOptions
$httpOptions
Methods
__construct()
Construct a new Account object.
public
__construct(string $discoveryUri, string|array<string|int, mixed> $httpOptions[, string $password = "" ][, string $baseUrl = null ]) : mixed
Parameters
- $discoveryUri : string
-
The URI to use for service discovery. This can be a partial URI, in the simplest case just a domain name. Note that if no protocol is given, https will be used. Unencrypted HTTP will only be done if explicitly given (e.g. http://example.com).
- $httpOptions : string|array<string|int, mixed>
-
The options for HTTP communication, including authentication credentials. An array with any of the keys (if no password is needed, the array may be empty, e.g. GSSAPI/Kerberos):
- username/password: The username and password for mechanisms requiring such credentials (e.g. Basic, Digest)
- bearertoken: The token to use for Bearer authentication (OAUTH2)
- verify: How to verify the server-side HTTPS certificate. True (the default) enables certificate verification against the default CA bundle of the OS, false disables certificate verification (note that this defeats the purpose of HTTPS and opens the door for man in the middle attacks). Set to the path of a PEM file containing a custom CA bundle to perform verification against a custom set of certification authorities.
- ssl_key: The path to the private key to use for mututal TLS verification, cannot be used with disabled verification, Guzzle will accept an array as well as a string, with the first element of the array being the filepath and the second being the password
- cert: The path to the PEM formatted client side certificate (password can be specified analog to ssl_key)
- preemptive_basic_auth: Set to true to always submit an Authorization header for HTTP Basic authentication (username and password options also required in this case) even if not challenged by the server. This may be required in rare use cases where the server allows unauthenticated access and will not challenge the client.
- query: Query options to append to every URL queried for this account, as an associative array of query options and values.
- headers: Headers to add to each request sent for this account, an associative array mapping header name to
header value (string) or header values (list
). Note that these headers are sent with all requests, including requests to other origins than that of the CardDAV server (e.g. after redirects), with the exception of Authorization and Cookie headers, which the HTTP client library removes on redirects to other origins. Do not use this option to pass credentials, use the username/password or bearertoken options instead. - auth_origin_callback: The credentials are only sent to the origin (scheme, host and port) of the URL of
the resource the request is made for (or the base URL of this Account for requests not related to a
specific resource). A callback function
function (string $targetUri, string $baseUri): boolcan be given to decide whether the credentials may be sent with a request to a different origin, e.g. after a redirect. $targetUri is the URI of the request, $baseUri the URI the credentials are bound to. Return true to send the credentials to $targetUri. The callback is not consulted for redirects that are followed by the HTTP client library automatically; credentials are never sent to a different origin for those. Credentials are never sent over plain HTTP if $baseUri uses HTTPS, regardless of the callback. Note that this option is not included in the serialized form of the Account (Account::jsonSerialize()) and must be set again after reconstructing the Account, e.g. using Account::setAuthOriginCallback(). During discovery, the callback is also consulted for servers outside the discovery domain, see Discovery::discoverAddressbooks().
Deprecated: username as string for authentication mechanisms requiring username / password.
- $password : string = ""
-
Deprecated: The password to use for authentication. This parameter is deprecated, include the password in the $httpOptions parameter. This parameter is ignored unless $httpOptions is used in its deprecated string form.
- $baseUrl : string = null
-
The URL of the CardDAV server without the path part (e.g. https://carddav.example.com:443). This URL is used as base URL for the underlying CardDavClient that can be retrieved using Account::getClient(). When relative URIs are passed to the client, they will be relative to this base URL. If this account is used for discovery with the Discovery service, this parameter can be omitted.
Tags
__toString()
Provides a readable form of the core properties of the Account.
public
__toString() : string
This is meant for printing to a human, not for parsing, and therefore may change without considering this a backwards incompatible change.
Return values
stringconstructFromArray()
Constructs an Account object from an array representation.
public
static constructFromArray(array<string|int, mixed> $props) : Account
This can be used to reconstruct/deserialize an Account from a stored (JSON) representation.
Parameters
- $props : array<string|int, mixed>
Tags
Return values
AccountfindAddressbookHomes()
Queries the given URI for the CARDDAV:addressbook-home-set property.
public
findAddressbookHomes(string $principalUri) : null|array<int, string>
Property description by RFC6352: The CARDDAV:addressbook-home-set property is meant to allow users to easily find the address book collections owned by the principal. Typically, users will group all the address book collections that they own under a common collection. This property specifies the URL of collections that are either address book collections or ordinary collections that have child or descendant address book collections owned by the principal.
Parameters
- $principalUri : string
-
The given URI should be (one of) the authenticated user's principal URI(s).
Return values
null|array<int, string> —The user's addressbook home URIs, or null in case of error. The returned URIs are suited to be used for queries with this client (i.e. either a full URI, or meaningful as relative URI to the base URI of this client).
findCurrentUserPrincipal()
Queries the given URI for the current-user-principal property.
public
findCurrentUserPrincipal(string $contextPathUri) : string|null
Property description by RFC5397: The DAV:current-user-principal property contains either a DAV:href or DAV:unauthenticated XML element. The DAV:href element contains a URL to a principal resource corresponding to the currently authenticated user. That URL MUST be one of the URLs in the DAV:principal-URL or DAV:alternate-URI-set properties defined on the principal resource and MUST be an http(s) scheme URL. When authentication has not been done or has failed, this property MUST contain the DAV:unauthenticated pseudo-principal. In some cases, there may be multiple principal resources corresponding to the same authenticated principal. In that case, the server is free to choose any one of the principal resource URIs for the value of the DAV:current-user-principal property. However, servers SHOULD be consistent and use the same principal resource URI for each authenticated principal.
Parameters
- $contextPathUri : string
-
The given URI should typically be a context path per the terminology of RFC6764.
Return values
string|null —The principal URI (string), or NULL in case of error. The returned URI is suited to be used for queries with this client (i.e. either a full URI, or meaningful as relative URI to the base URI of this client).
getAuthOriginCallback()
Returns the callback that decides whether the credentials may be sent to a different origin, if any.
public
getAuthOriginCallback() : callable|null
Tags
Return values
callable|nullgetClient()
Provides a CardDavClient object to interact with the server for this account.
public
getClient([string $baseUrl = null ]) : CardDavClient
Parameters
- $baseUrl : string = null
-
A base URL to use by the client to resolve relative URIs. If not given, the base url of the Account is used. This is useful, for example, to override the base path with that of a collection.
Return values
CardDavClient —A CardDavClient object to interact with the server for this account.
getDiscoveryUri()
Returns the discovery URI for this Account.
public
getDiscoveryUri() : string
Return values
stringgetUrl()
Returns the base URL of the CardDAV service.
public
getUrl() : string
Return values
stringjsonSerialize()
Allows to serialize an Account object to JSON.
public
jsonSerialize() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>setAuthOriginCallback()
Sets the callback that decides whether the credentials may be sent to a different origin.
public
setAuthOriginCallback(callable|null $callback) : void
This is equivalent to the auth_origin_callback HTTP option (see Account::__construct()). As the callback is not included in the serialized form of the Account, this method can be used to set it again after reconstructing an Account using Account::constructFromArray(). The callback applies to all requests made for this account, including those for resources created before setting the callback.
Parameters
- $callback : callable|null
-
The callback, or null to remove the callback.
Tags
setUrl()
Set the base URL of this account once the service URL has been discovered.
public
setUrl(string $url) : void
Parameters
- $url : string