PHP Class Turba_Api, horde

This file defines Turba's external API interface. Other applications can interact with Turba through this API. Copyright 2009-2015 Horde LLC (http://www.horde.org/) See the enclosed file LICENSE for license information (ASL). If you did did not receive this file, see http://www.horde.org/licenses/apache.
Author: Michael Slusarz ([email protected])
Inheritance: extends Horde_Registry_Api
ファイルを表示 Open project: horde/horde

Protected Properties

Property Type Description
$_links array Links.
$_noPerms array The listing of API calls that do not require permissions checking.

Public Methods

Method Description
addAddressbook ( string $name, array $params = [] ) : string Create a new addressbook
addClient ( array $attributes = [] ) : boolean Adds a client to the client source.
addField ( string | array $address = '', string $name = '', string $field = '', string $value = '', string $source = '' ) Sets the value of the specified attribute of a contact
addGroup ( string $name, array $members, array $opts = [] ) : array Adds a group (and its members) to the source provided.
browse ( string $path = '', array $properties = ['name', 'icon', 'browseable'] ) : array Browses through Turba's object tree.
clientFields ( ) : array Returns the available client fields.
commentCallback ( integer $id ) : mixed Callback for comment API.
delete ( string | array $uid, string | array $sources = null ) : boolean Deletes a contact identified by UID.
deleteAddressbook ( string $id ) Delete the specified addressbook.
deleteClient ( string $objectId = '' ) : boolean Deletes a client
deleteField ( string $address = '', string $field = '', array $sources = [] ) Deletes a field value.
export ( string $uid, mixed $contentType, string | array $sources = null, array $fields = null, array $options = [] ) : mixed Export a contact, identified by UID, in the requested contentType.
fields ( string $source = null ) : array Returns a list of fields avaiable in a source.
getActionTimestamp ( string $uid, string $action, string | array $sources = null, boolean $modSeq = false ) : integer Returns the timestamp of an operation for a given UID and action.
getAllAttributeValues ( string $field = '', array $sources = [] ) : array Retrieves a list of all possible values of a field in specified source(s).
getChanges ( integer $start, integer $end, boolean $isModSeq = false, string | array $sources = null ) : array Method for obtaining all server changes between two timestamps.
getChangesByModSeq ( integer $start, integer $end, string | array $sources = null ) : array Return all changes occuring between the specified modification sequences.
getClient ( string $objectId = '' ) : array Returns a contact from the client source.
getClientSource ( ) : string Returns the client source name.
getClients ( array $objectIds = [] ) : array Returns mulitple contacts from the client source.
getContact ( string $source = null, string $objectId = '' ) : array Retrieves a contact.
getContacts ( string $source = '', array $objectIds = [] ) : array Retrieves a set of contacts from a single source.
getDefaultShare ( ) : string Retrieve the UID for the current user's default Turba share.
getField ( string $address = '', string $field = '', array $sources = [], boolean $strict = false, boolean $multiple = false ) : array Returns a field value.
getGalUid ( ) : string | boolean Retrieve the UID for the Global Address List source.
getGroupMembers ( string $gid, boolean $subGroups = false ) : array Returns a list of all members belonging to a contact group.
getGroupMemberships ( string $user, boolean $parentGroups = false ) : array Returns all contact groups that the specified user is a member of.
getGroupObject ( string $gid ) : array Returns a contact group hash.
getGroupObjects ( ) : array Returns all contact groups.
getHighestModSeq ( string $id = null ) : integer Return the largest modification sequence from the history backend.
getOwnContactObject ( ) : array Helper function to return the user's own contact object
getSourcesConfig ( type $filter = [] ) : array Obtain an array of $cfgSource entries matching the filter criteria.
hasComments ( ) : boolean Does this API allow comments?
import ( string $content, string $contentType = 'array', string $source = null, array $options = [] ) : string Import a contact represented in the specified contentType.
listBy ( string $action, integer $timestamp, string | array $sources = null, integer $end = null, boolean $isModSeq = false ) : array Returns an array of UIDs for contacts that have had a given action since a certain time.
listShares ( integer $perms = Horde_Perms::READ ) : array Lists all shares the current user has access to.
listTagInfo ( array $tags = null, $user = null ) : array Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.
listTimeObjectCategories ( ) : array Retrieves a list of available time objects categories.
listTimeObjects ( array $time_categories, mixed $start, mixed $end ) : array Lists birthdays and/or anniversaries as time objects.
listUids ( string | array $sources = null ) : array Returns an array of UIDs for all contacts that the current user is authorized to see.
listUserGroupObjects ( ) : array GroupObject API - Lists all turba lists for the current user that can be treated as Horde_Group objects.
ownContact ( ) : array Export the user's own contact as a hash.
ownVCard ( ) : string Exports the user's own contact as a vCard string.
path_delete ( string $path ) : string Deletes a file from the Turba tree.
replace ( string $uid, mixed $content, string $contentType, string | array $sources = null ) : boolean Replaces the contact identified by UID with the content represented in the specified contentType.
search ( mixed $names = null, array $opts = [] ) : mixed Returns a contact search result.
searchClients ( array $names = [], array $fields = [], boolean $matchBegin = false ) : array Search for clients.
searchTags ( array $names, integer $max = 10, integer $from, string $resource_type = '', string $user = null, boolean $raw = false ) : array SearchTags API: Returns an application-agnostic array (useful for when doing a tag search across multiple applications)
sources ( boolean $writeable = false, boolean $sync_only = false ) : array Returns a list of available sources.
updateAddressbook ( string $id, array $info ) Update an existing addressbook's name or description.
updateClient ( string $objectId = '', array $attributes = [] ) : boolean Updates client data.

Protected Methods

Method Description
_encodeContent ( $content )
_getContactImageUrl ( $obj )
_getGroupObject ( $source, $key )
_getSource ( $source )
_getSources ( $sources, $synchronize = false, $end = false )
_modified ( $uid, $sources )

Method Details

_encodeContent() protected method

protected _encodeContent ( $content )

_getContactImageUrl() protected method

protected _getContactImageUrl ( $obj )

_getGroupObject() protected method

protected _getGroupObject ( $source, $key )

_getSource() protected method

protected _getSource ( $source )

_getSources() protected method

protected _getSources ( $sources, $synchronize = false, $end = false )

_modified() protected method

protected _modified ( $uid, $sources )

addAddressbook() public method

Create a new addressbook
Since: 4.2.0
public addAddressbook ( string $name, array $params = [] ) : string
$name string The display name for the addressbook.
$params array Any addtional parameters needed. - synchronize: (boolean) If true, add address book to the list of address books to syncronize. DEFAULT: false (do not add to the list). @since 4.2.1
return string The new addressbook's id (share name).

addClient() public method

Adds a client to the client source.
public addClient ( array $attributes = [] ) : boolean
$attributes array Array containing the client attributes.
return boolean

addField() public method

Sets the value of the specified attribute of a contact
public addField ( string | array $address = '', string $name = '', string $field = '', string $value = '', string $source = '' )
$address string | array Contact email address(es).
$name string Contact name.
$field string Field to update.
$value string Field value to set.
$source string Contact source.

addGroup() public method

Adds a group (and its members) to the source provided.
public addGroup ( string $name, array $members, array $opts = [] ) : array
$name string Group name.
$members array An array of members to add to the group. Format is the same as the 'array' argument to the import() API function.
$opts array Additional options:
  - attr: (array) Additional attributes to add to group.
  - source: (string) Source to import contacts to.
return array An array with the following keys:
  - added: (integer) The number of addresses added to the group.
  - uid: (string) The uid of the group object.

browse() public method

Browses through Turba's object tree.
public browse ( string $path = '', array $properties = ['name', 'icon', 'browseable'] ) : array
$path string The path of the tree to browse.
$properties array The item properties to return. Defaults to 'name', 'icon', and 'browseable'.
return array Content of the specified path.

clientFields() public method

Returns the available client fields.
public clientFields ( ) : array
return array An array describing the fields.

commentCallback() public method

Callback for comment API.
public commentCallback ( integer $id ) : mixed
$id integer Internal data identifier.
return mixed Name of object on success, false on failure.

delete() public method

Deletes a contact identified by UID.
public delete ( string | array $uid, string | array $sources = null ) : boolean
$uid string | array Identify the contact to delete, either a single UID or an array.
$sources string | array The source(s) from which the contact will be deleted.
return boolean Success or failure.

deleteAddressbook() public method

Delete the specified addressbook.
Since: 4.2.0
public deleteAddressbook ( string $id )
$id string The addressbook id.

deleteClient() public method

Deletes a client
public deleteClient ( string $objectId = '' ) : boolean
$objectId string The unique id of the client
return boolean

deleteField() public method

Deletes a field value.
public deleteField ( string $address = '', string $field = '', array $sources = [] )
$address string Contact email address.
$field string Field to delete value for.
$sources array Sources to delete value from.

export() public method

Export a contact, identified by UID, in the requested contentType.
public export ( string $uid, mixed $contentType, string | array $sources = null, array $fields = null, array $options = [] ) : mixed
$uid string Identify the contact to export.
$contentType mixed What format should the data be in? - text/directory: Returns RFC2426 vcard3.0 - text/vcard: Returns RFC2426 vcard3.0 - text/x-vcard: Returns imc.org vcard 2.1 format. - array: Returns a raw array - activesync: Returns a Horde_ActiveSync_Message_Contact:: object
$sources string | array The source(s) from which the contact will be exported.
$fields array Hash of field names and Horde_SyncMl_Property properties with the requested fields.
$options array Any additional options to be passed to the exporter. Currently supported: - skip_empty: (boolean) {text/vcard or text/x-vcard} Set to true to not output empty properties. DEFAULT: false. - protocolversion: (float) {activesync} The EAS version to support DEFAULT: 2.5 - bodyprefs: (array) {activesync} A BODYPREFERENCE array. DEFAULT: none (No body prefs enforced). - truncation: (integer) {activesync} Truncate event body to this length. DEFAULT: none (No truncation).
return mixed The requested data.

fields() public method

Returns a list of fields avaiable in a source.
public fields ( string $source = null ) : array
$source string The source name.
return array An array describing the fields. Keys are the field name, values are arrays with these keys: - name: (string) Field name. - label: (string) Field label. - search: (boolean) Can this field be searched? - type: (string) See turba/config/attributes.php.

getActionTimestamp() public method

Returns the timestamp of an operation for a given UID and action.
public getActionTimestamp ( string $uid, string $action, string | array $sources = null, boolean $modSeq = false ) : integer
$uid string The UID to look for.
$action string The action to check for - add, modify, or delete.
$sources string | array The source(s) for which to retrieve the history.
$modSeq boolean Request a modification sequence instead of timestamp. @since 4.1.1
return integer The timestamp for this action.

getAllAttributeValues() public method

Retrieves a list of all possible values of a field in specified source(s).
public getAllAttributeValues ( string $field = '', array $sources = [] ) : array
$field string Field name to check.
$sources array Array containing the sources to look in.
return array An array of fields and possible values.

getChanges() public method

Essentially a wrapper around listBy(), but returns an array containing all adds, edits, and deletions.
public getChanges ( integer $start, integer $end, boolean $isModSeq = false, string | array $sources = null ) : array
$start integer The starting timestamp
$end integer The ending timestamp.
$isModSeq boolean If true, $start and $end are modification sequences and not timestamps. @since 4.1.1
$sources string | array The sources to check. @since 4.2.0
return array A hash with 'add', 'modify' and 'delete' arrays.

getChangesByModSeq() public method

Return all changes occuring between the specified modification sequences.
Since: 4.1.1
public getChangesByModSeq ( integer $start, integer $end, string | array $sources = null ) : array
$start integer The starting modseq.
$end integer The ending modseq.
$sources string | array The sources to check. @since 4.2.0
return array The changes @see getChanges()

getClient() public method

Returns a contact from the client source.
public getClient ( string $objectId = '' ) : array
$objectId string Client unique ID.
return array Array of client data.

getClientSource() public method

Returns the client source name.
public getClientSource ( ) : string
return string The name of the source to use with the clients api.

getClients() public method

Returns mulitple contacts from the client source.
public getClients ( array $objectIds = [] ) : array
$objectIds array client unique ids.
return array An array of clients data.

getContact() public method

Retrieves a contact.
public getContact ( string $source = null, string $objectId = '' ) : array
$source string The source name where the contact is stored
$objectId string The unique id of the contact to retrieve
return array The retrieved contact.

getContacts() public method

Retrieves a set of contacts from a single source.
public getContacts ( string $source = '', array $objectIds = [] ) : array
$source string The source name where the contact is stored
$objectIds array The unique ids of the contact to retrieve.
return array The retrieved contact.

getDefaultShare() public method

Retrieve the UID for the current user's default Turba share.
public getDefaultShare ( ) : string
return string UID.

getField() public method

Returns a field value.
public getField ( string $address = '', string $field = '', array $sources = [], boolean $strict = false, boolean $multiple = false ) : array
$address string Contact email address.
$field string Field to get.
$sources array Sources to check.
$strict boolean Match the email address strictly.
$multiple boolean Return more than one entry if found and true, return an error if this is false.
return array An array of field value(s).

getGalUid() public method

Retrieve the UID for the Global Address List source.
public getGalUid ( ) : string | boolean
return string | boolean The UID or false if none configured.

getGroupMembers() public method

Returns a list of all members belonging to a contact group.
public getGroupMembers ( string $gid, boolean $subGroups = false ) : array
$gid string The group identifier
$subGroups boolean Also include members of any subgroups?
return array An array of group members (identified by email address).

getGroupMemberships() public method

Returns all contact groups that the specified user is a member of.
public getGroupMemberships ( string $user, boolean $parentGroups = false ) : array
$user string The user.
$parentGroups boolean Include user as a member of the any parent group as well.
return array An array of group identifiers that the specified user is a member of.

getGroupObject() public method

Returns a contact group hash.
public getGroupObject ( string $gid ) : array
$gid string The group identifier.
return array A hash defining the group.

getGroupObjects() public method

Returns all contact groups.
public getGroupObjects ( ) : array
return array A list of group hashes.

getHighestModSeq() public method

Return the largest modification sequence from the history backend.
Since: 4.1.1
public getHighestModSeq ( string $id = null ) : integer
$id string Addressbook id to return highest MODSEQ for. If null, the highest MODSEQ across all addressbooks is returned. @since 4.2.0
return integer The modseq.

getOwnContactObject() public method

Helper function to return the user's own contact object
public getOwnContactObject ( ) : array
return array An array containing the following keys: - contact: (Turba_Object) Object representing the user's own contact. - source: (string) The source of the user's own contact.

getSourcesConfig() public method

Obtain an array of $cfgSource entries matching the filter criteria.
public getSourcesConfig ( type $filter = [] ) : array
$filter type A single key -> value hash to filter the sources.
return array

hasComments() public method

Does this API allow comments?
public hasComments ( ) : boolean
return boolean True if API allows comments.

import() public method

Import a contact represented in the specified contentType.
public import ( string $content, string $contentType = 'array', string $source = null, array $options = [] ) : string
$content string The content of the contact.
$contentType string What format is the data in? Currently supports array, text/directory, text/vcard, text/x-vcard, and activesync.
$source string The source into which the contact will be imported.
$options array Additional options: - match_on_email: (boolean) If true, will detect entry as duplicate if ANY email field matches. Useful for automatically adding contacts from an email application, such as IMP. @since 4.2.9
return string The new UID.

listBy() public method

Returns an array of UIDs for contacts that have had a given action since a certain time.
public listBy ( string $action, integer $timestamp, string | array $sources = null, integer $end = null, boolean $isModSeq = false ) : array
$action string The action to check for - add, modify, or delete.
$timestamp integer The time to start the search.
$sources string | array The source(s) for which to retrieve the history.
$end integer The optional ending timestamp.
$isModSeq boolean If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1
return array An array of UIDs matching the action and time criteria.

listShares() public method

Lists all shares the current user has access to.
public listShares ( integer $perms = Horde_Perms::READ ) : array
$perms integer
return array of Turba_Share objects.

listTagInfo() public method

Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.
public listTagInfo ( array $tags = null, $user = null ) : array
$tags array An optional array of tag_ids. If omitted, all tags will be included.
return array An array containing tag_name, and total

listTimeObjectCategories() public method

Retrieves a list of available time objects categories.
public listTimeObjectCategories ( ) : array
return array An array of all configured time object categories.

listTimeObjects() public method

Lists birthdays and/or anniversaries as time objects.
public listTimeObjects ( array $time_categories, mixed $start, mixed $end ) : array
$time_categories array The time categories (from listTimeObjectCategories) to list.
$start mixed The start date of the period.
$end mixed The end date of the period.
return array An array of timeObject results.

listUids() public method

Returns an array of UIDs for all contacts that the current user is authorized to see.
public listUids ( string | array $sources = null ) : array
$sources string | array The name(s) of the source(s) to return contacts of. If empty, the current user's sync sources or default source are used.
return array An array of UIDs for all contacts the user can access.

listUserGroupObjects() public method

GroupObject API - Lists all turba lists for the current user that can be treated as Horde_Group objects.
public listUserGroupObjects ( ) : array
return array A hash of all visible groups in the form of group_id => group_name

ownContact() public method

Export the user's own contact as a hash.
public ownContact ( ) : array
return array The contact hash.

ownVCard() public method

Exports the user's own contact as a vCard string.
public ownVCard ( ) : string
return string The requested vCard data.

path_delete() public method

Deletes a file from the Turba tree.
public path_delete ( string $path ) : string
$path string The path to the file.
return string The event's UID.

replace() public method

Replaces the contact identified by UID with the content represented in the specified contentType.
public replace ( string $uid, mixed $content, string $contentType, string | array $sources = null ) : boolean
$uid string Idenfity the contact to replace.
$content mixed The content of the contact.
$contentType string What format is the data in? Currently supports array, text/directory, text/vcard, text/x-vcard and activesync.
$sources string | array The source(s) where the contact will be replaced.
return boolean Success or failure.

searchClients() public method

Search for clients.
public searchClients ( array $names = [], array $fields = [], boolean $matchBegin = false ) : array
$names array The search filter values.
$fields array The fields to search in.
$matchBegin boolean Match word boundaries only.
return array A hash containing the search results.

searchTags() public method

The 'raw' results array can be returned instead by setting $raw = true.
public searchTags ( array $names, integer $max = 10, integer $from, string $resource_type = '', string $user = null, boolean $raw = false ) : array
$names array An array of tag_names to search for.
$max integer The maximum number of resources to return.
$from integer The number of the resource to start with.
$resource_type string The resource type [bookmark, '']
$user string Restrict results to resources owned by $user.
$raw boolean Return the raw data?
return array An array of results:
 'title'    - The title for this resource.
 'desc'     - A terse description of this resource.
 'view_url' - The URL to view this resource.
 'app'      - The Horde application this resource belongs to.
 'icon'     - URL to an image.

sources() public method

Returns a list of available sources.
public sources ( boolean $writeable = false, boolean $sync_only = false ) : array
$writeable boolean If true, limits to writeable sources.
$sync_only boolean Only include synchable address books.
return array An array of the available sources. Keys are source IDs, values are source titles.

updateAddressbook() public method

Update an existing addressbook's name or description.
Since: 4.2.0
public updateAddressbook ( string $id, array $info )
$id string The addressbook id.
$info array The info to change: - name: The addressbook's display name. - desc: The addressbook's description.

updateClient() public method

Updates client data.
public updateClient ( string $objectId = '', array $attributes = [] ) : boolean
$objectId string The unique id of the client.
$attributes array An array of client attributes.
return boolean

Property Details

$_noPerms protected_oe property

The listing of API calls that do not require permissions checking.
protected array $_noPerms
return array