Nextcloud PHP API (stable18)

IManager

This class provides access to the contacts app. Use this class exclusively if you want to access contacts.

Contacts in general will be expressed as an array of key-value-pairs. The keys will match the property names defined in https://tools.ietf.org/html/rfc2426#section-1

Proposed workflow for working with contacts:

  • search for the contacts
  • manipulate the results array
  • createOrUpdate will save the given contacts overwriting the existing data

For updating it is mandatory to keep the id. Without an id a new contact will be created.

Tags
since
6.0.0

Table of Contents

clear()  : void
removes all registered address book instances
createOrUpdate()  : array
This function is used to create a new contact if 'id' is not given or not present.
delete()  : bool
This function can be used to delete the contact identified by the given id
getAddressBooks()  : array
Return a list of the user's addressbooks display names
getUserAddressBooks()  : \OCP\Contacts\IAddressBook[]
Return a list of the user's addressbooks
isEnabled()  : bool
Check if contacts are available (e.g. contacts app enabled)
register()  : void
In order to improve lazy loading a closure can be registered which will be called in case address books are actually requested
registerAddressBook()  : void
Registers an address book
search()  : array
This function is used to search and find contacts within the users address books.
unregisterAddressBook()  : void
Unregisters an address book

Methods

clear()

removes all registered address book instances

public clear() : void
Tags
since
6.0.0

createOrUpdate()

This function is used to create a new contact if 'id' is not given or not present.

public createOrUpdate(array $properties, string $address_book_key) : array

Otherwise the contact will be updated by replacing the entire data set.

Parameters
$properties : array

this array if key-value-pairs defines a contact

$address_book_key : string

identifier of the address book in which the contact shall be created or updated

Tags
since
6.0.0
Return values
array —

an array representing the contact just created or updated

delete()

This function can be used to delete the contact identified by the given id

public delete(object $id, string $address_book_key) : bool
Parameters
$id : object

the unique identifier to a contact

$address_book_key : string

identifier of the address book in which the contact shall be deleted

Tags
since
6.0.0
Return values
bool —

successful or not

getAddressBooks()

Return a list of the user's addressbooks display names

public getAddressBooks() : array
Tags
since
6.0.0
deprecated
16.0.0
  • Use $this->getUserAddressBooks() instead
Return values
array —

getUserAddressBooks()

Return a list of the user's addressbooks

public getUserAddressBooks() : \OCP\Contacts\IAddressBook[]
Tags
since
16.0.0
Return values
\OCP\Contacts\IAddressBook[] —

isEnabled()

Check if contacts are available (e.g. contacts app enabled)

public isEnabled() : bool
Tags
since
6.0.0
Return values
bool —

true if enabled, false if not

register()

In order to improve lazy loading a closure can be registered which will be called in case address books are actually requested

public register(Closure $callable) : void
Parameters
$callable : Closure
Tags
since
6.0.0

registerAddressBook()

Registers an address book

public registerAddressBook(IAddressBook $address_book) : void
Parameters
$address_book : IAddressBook
Tags
since
6.0.0

search()

This function is used to search and find contacts within the users address books.

public search(string $pattern[, array $searchProperties = array() ][, array $options = array() ]) : array

In case $pattern is empty all contacts will be returned.

Example: Following function shows how to search for contacts for the name and the email address.

public static function getMatchingRecipient($term) {
    $cm = \OC::$server->getContactsManager();
    // The API is not active -> nothing to do
    if (!$cm->isEnabled()) {
        return array();
    }

    $result = $cm->search($term, array('FN', 'EMAIL'));
    $receivers = array();
    foreach ($result as $r) {
        $id = $r['id'];
        $fn = $r['FN'];
        $email = $r['EMAIL'];
        if (!is_array($email)) {
            $email = array($email);
        }

        // loop through all email addresses of this contact
        foreach ($email as $e) {
        $displayName = $fn . " <$e>";
        $receivers[] = array(
            'id'    => $id,
            'label' => $displayName,
            'value' => $displayName);
        }
    }

    return $receivers;
}
Parameters
$pattern : string

which should match within the $searchProperties

$searchProperties : array = array()

defines the properties within the query pattern should match

$options : array = array()

= array() to define the search behavior

  • 'escape_likeparam' - If set to false wildcards and % are not escaped
  • 'limit' - Set a numeric limit for the search results
  • 'offset' - Set the offset for the limited search results
Tags
since
6.0.0
Return values
array —

an array of contacts which are arrays of key-value-pairs

unregisterAddressBook()

Unregisters an address book

public unregisterAddressBook(IAddressBook $address_book) : void
Parameters
$address_book : IAddressBook
Tags
since
6.0.0

Search results