Nextcloud PHP API (master)

IManager
in

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

Methods

clear()  : void
removes all registered address book instances
createOrUpdate()  : array<string|int, mixed>|null
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
getUserAddressBooks()  : array<string|int, 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<string|int, mixed>
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<string|int, mixed> $properties, string $addressBookKey) : array<string|int, mixed>|null

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

Parameters
$properties : array<string|int, mixed>

this array if key-value-pairs defines a contact

$addressBookKey : string

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

Tags
since
6.0.0
Return values
array<string|int, mixed>|null —

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(int $id, string $addressBookKey) : bool
Parameters
$id : int

the unique identifier to a contact

$addressBookKey : string

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

Tags
since
6.0.0
Return values
bool —

successful or not

getUserAddressBooks()

Return a list of the user's addressbooks

public getUserAddressBooks() : array<string|int, IAddressBook>
Tags
since
16.0.0
Return values
array<string|int, 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 $addressBook) : void
Parameters
$addressBook : 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<string|int, mixed> $searchProperties = [] ][, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>

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<string|int, mixed> = []

defines the properties within the query pattern should match

$options : array<string|int, mixed> = []

= array() to define the search behavior

  • 'types' boolean (since 15.0.0) If set to true, fields that come with a TYPE property will be an array example: ['id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => ['type => 'HOME', 'value' => 'g@h.i']]
  • 'escape_like_param' - 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
  • 'enumeration' - (since 23.0.0) Whether user enumeration on system address book is allowed
  • 'fullmatch' - (since 23.0.0) Whether matching on full detail in system address book is allowed
  • 'strict_search' - (since 23.0.0) Whether the search pattern is full string or partial search
Tags
psalm-param

array{types?: bool, escape_like_param?: bool, limit?: int, offset?: int, enumeration?: bool, fullmatch?: bool, strict_search?: bool} $options

since
6.0.0
Return values
array<string|int, mixed> —

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

unregisterAddressBook()

Unregisters an address book

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

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results