Documentation

AddressBook extends Collection
in package

Application

implements IAddressBook, IProperties, IACL, ISyncCollection, IMultiGet Uses ACLTrait

The AddressBook class represents a CardDAV addressbook, owned by a specific user.

The AddressBook can contain multiple vcards

Interfaces, Classes and Traits

IAddressBook: AddressBook interface.
IProperties: IProperties interface.
IACL: ACL-enabled node.
ISyncCollection: If a class extends ISyncCollection, it supports WebDAV-sync.
IMultiGet: IMultiGet.

$addressBookInfo : array<string|int, mixed>: This is an array with addressbook information.
$carddavBackend : BackendInterface: CardDAV backend.
__construct() : mixed: Constructor.
childExists() : bool: Checks is a child-node exists.
createDirectory() : mixed: Creates a new directory.
createFile() : string|null: Creates a new file.
delete() : mixed: Deletes the entire addressbook.
getACL() : array<string|int, mixed>: Returns a list of ACE's for this node.
getChanges() : array<string|int, mixed>: The getChanges method returns all the changes that have happened, since the specified syncToken and the current collection.
getChild() : Card: Returns a card.
getChildACL() : array<string|int, mixed>: This method returns the ACL's for card nodes in this address book.
getChildren() : array<string|int, mixed>: Returns the full list of cards.
getGroup() : string|null: Returns a group principal.
getLastModified() : mixed: Returns the last modification date as a unix timestamp.
getMultipleChildren() : array<string|int, mixed>: This method receives a list of paths in it's first argument.
getName() : string: Returns the name of the addressbook.
getOwner() : string|null: Returns the owner principal.
getProperties() : array<string|int, mixed>: Returns a list of properties for this nodes.
getSupportedPrivilegeSet() : array<string|int, mixed>|null: Returns the list of supported privileges for this node.
getSyncToken() : string|null: This method returns the current sync-token for this collection.
propPatch() : mixed: Updates properties on this node.
setACL() : mixed: Updates the ACL.
setName() : mixed: Renames the addressbook.

$addressBookInfo

This is an array with addressbook information.


    protected
        array<string|int, mixed>
    $addressBookInfo

$carddavBackend

CardDAV backend.


    protected
        BackendInterface
    $carddavBackend

__construct()

Constructor.


    public
                __construct(BackendInterface $carddavBackend, array<string|int, mixed> $addressBookInfo) : mixed

Parameters

$carddavBackend : BackendInterface
$addressBookInfo : array<string|int, mixed>

Return values

mixed —

childExists()

Checks is a child-node exists.


    public
                childExists(string $name) : bool

It is generally a good idea to try and override this. Usually it can be optimized.

Parameters

$name : string

Return values

bool —

createDirectory()

Creates a new directory.


    public
                createDirectory(string $name) : mixed

We actually block this, as subdirectories are not allowed in addressbooks.

Parameters

$name : string

Return values

mixed —

createFile()

Creates a new file.


    public
                createFile(string $name[, resource $vcardData = null ]) : string|null

The contents of the new file must be a valid VCARD.

This method may return an ETag.

Parameters

$name : string
$vcardData : resource = null

Return values

string|null —

delete()

Deletes the entire addressbook.


    public
                delete() : mixed

Return values

mixed —

getACL()

Returns a list of ACE's for this node.


    public
                getACL() : array<string|int, mixed>

Each ACE has the following properties:

'privilege', a string such as {DAV:}read or {DAV:}write. These are currently the only supported privileges
'principal', a url to the principal who owns the node
'protected' (optional), indicating that this ACE is not allowed to be updated.

Return values

array<string|int, mixed> —

getChanges()

The getChanges method returns all the changes that have happened, since the specified syncToken and the current collection.


    public
                getChanges(string $syncToken, int $syncLevel[, int $limit = null ]) : array<string|int, mixed>

This function should return an array, such as the following:

[ 'syncToken' => 'The current synctoken', 'added' => [ 'new.txt', ], 'modified' => [ 'modified.txt', ], 'deleted' => [ 'foo.php.bak', 'old.txt' ] ];

The syncToken property should reflect the current syncToken of the collection, as reported getSyncToken(). This is needed here too, to ensure the operation is atomic.

If the syncToken is specified as null, this is an initial sync, and all members should be reported.

The modified property is an array of nodenames that have changed since the last token.

The deleted property is an array with nodenames, that have been deleted from collection.

The second argument is basically the 'depth' of the report. If it's 1, you only have to report changes that happened only directly in immediate descendants. If it's 2, it should also include changes from the nodes below the child collections. (grandchildren)

The third (optional) argument allows a client to specify how many results should be returned at most. If the limit is not specified, it should be treated as infinite.

If the limit (infinite or not) is higher than you're willing to return, you should throw a Sabre\DAV\Exception\TooMuchMatches() exception.

If the syncToken is expired (due to data cleanup) or unknown, you must return null.

The limit is 'suggestive'. You are free to ignore it.

Parameters

$syncToken : string
$syncLevel : int
$limit : int = null

Return values

array<string|int, mixed> —

getChild()

Returns a card.


    public
                getChild(string $name) : Card

Parameters

$name : string

Return values

Card —

getChildACL()

This method returns the ACL's for card nodes in this address book.


    public
                getChildACL() : array<string|int, mixed>

The result of this method automatically gets passed to the card nodes in this address book.

Return values

array<string|int, mixed> —

getChildren()

Returns the full list of cards.


    public
                getChildren() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getGroup()

Returns a group principal.


    public
                getGroup() : string|null

This must be a url to a principal, or null if there's no owner

Return values

string|null —

getLastModified()

Returns the last modification date as a unix timestamp.


    public
                getLastModified() : mixed

Return values

mixed —

getMultipleChildren()

This method receives a list of paths in it's first argument.


    public
                getMultipleChildren(array<string|int, string> $paths) : array<string|int, mixed>

It must return an array with Node objects.

If any children are not found, you do not have to return them.

Parameters

$paths : array<string|int, string>

Return values

array<string|int, mixed> —

getName()

Returns the name of the addressbook.


    public
                getName() : string

Return values

string —

getOwner()

Returns the owner principal.


    public
                getOwner() : string|null

This must be a url to a principal, or null if there's no owner

Return values

string|null —

getProperties()

Returns a list of properties for this nodes.


    public
                getProperties(array<string|int, mixed> $properties) : array<string|int, mixed>

The properties list is a list of propertynames the client requested, encoded in clark-notation {xmlnamespace}tagname

If the array is empty, it means 'all properties' were requested.

Parameters

$properties : array<string|int, mixed>

Return values

array<string|int, mixed> —

getSupportedPrivilegeSet()

Returns the list of supported privileges for this node.


    public
                getSupportedPrivilegeSet() : array<string|int, mixed>|null

The returned data structure is a list of nested privileges. See Sabre\DAVACL\Plugin::getDefaultSupportedPrivilegeSet for a simple standard structure.

If null is returned from this method, the default privilege set is used, which is fine for most common usecases.

Return values

array<string|int, mixed>|null —

getSyncToken()

This method returns the current sync-token for this collection.


    public
                getSyncToken() : string|null

This can be any string.

If null is returned from this function, the plugin assumes there's no sync information available.

Return values

string|null —

propPatch()

Updates properties on this node.


    public
                propPatch(PropPatch $propPatch) : mixed

This method received a PropPatch object, which contains all the information about the update.

To update specific properties, call the 'handle' method on this object. Read the PropPatch documentation for more information.

Parameters

$propPatch : PropPatch

Return values

mixed —

setACL()

Updates the ACL.


    public
                setACL(array<string|int, mixed> $acl) : mixed

This method will receive a list of new ACE's as an array argument.

Parameters

$acl : array<string|int, mixed>

Return values

mixed —

setName()

Renames the addressbook.


    public
                setName(string $newName) : mixed

Parameters

$newName : string

Return values

mixed —