PHP Class Turba_Driver, horde

Author: Chuck Hagenbuch ([email protected])

Author: Jon Parise ([email protected])

Inheritance: implements Countable

Show file Open project: horde/horde Class Usage Examples

Public Properties

Property	Type	Description
$alternativeName	string	The name of a field to use as an alternative to the name field if that one is empty.
$approximate	array	Array of fields to search "approximately" (@see config/backends.php).
$fields	array	List of all fields that can be accessed in the backend (excludes composite attributes, etc.).
$listNameField	string	The name of a field to store contact list names in if not the default.
$map	array	Hash describing the mapping between Turba attributes and driver-specific fields.
$strict	array	Array of fields that must match exactly.
$tabs	array	Hash with all tabs and their fields.
$title	string	The symbolic title of this source.

Protected Properties

Property	Type	Description
$_asMap	array	Mapping of Turba attributes to ActiveSync fields.
$_capabilities	array	What can this backend do?
$_contact_owner	string	Hold the value for the owner of this address book.
$_count	integer	Number of contacts in this source.
$_name	string	The internal name of this source.
$_objectOptions	array	Any additional options passed to Turba_Object constructors.
$_params	array	Hash holding the driver's additional parameters.

Public Methods

Method	Description
__construct ( string $name = '', array $params = [] )	Constructs a new Turba_Driver object.
add ( array $attributes ) : string	Adds a new entry to the contact source.
canAdd ( ) : boolean	Returns ability of the backend to add new contacts.
checkDefaultShare ( Horde_Share_Object $share, array $srcconfig ) : boolean	Check if the passed in share is the default share for this source.
count ( ) : integer	Returns the number of contacts of the current user in this address book.
createShare ( string $share_name, array $params ) : Horde_Share	Creates a new Horde_Share for this source type.
delete ( string $object_id, boolean $remove_tags = true )	Deletes the specified entry from the contact source.
deleteAll ( string $sourceName = null )	Deletes all contacts from an address book.
fromASContact ( Horde_ActiveSync_Message_Contact $message ) : array	Convert an ActiveSync contact message into a hash suitable for importing via self::add().
getBlobs ( ) : array	Returns the attributes that are blob types.
getContactOwner ( ) : string	Return the owner to use when searching or creating contacts in this address book.
getCriteria ( ) : array	Returns the criteria available for this source except '__key'.
getDateFields ( ) : array	Returns the attributes that represent dates.
getFields ( ) : array	Returns all non-composite fields for this source. Useful for importing and exporting data, etc.
getName ( )	Return the name of this address book.
getObject ( string $objectId ) : Turba_Object	Retrieves one object from the source.
getObjects ( array $objectIds ) : array	Retrieves a set of objects from the source.
getParams ( ) : array	Returns the current driver's additional parameters.
getTimeObjectTurbaList ( Horde_Date $start, Horde_Date $end, string $field ) : Turba_List	Default implementation for obtaining a Turba_List to get TimeObjects out of.
hasCapability ( string $capability ) : boolean	Checks if this backend has a certain capability.
hasPermission ( integer $perm ) : boolean	Checks if the current user has the requested permissions on this address book.
listTimeObjects ( Horde_Date $start, Horde_Date $end, string $category ) : array	Returns a list of birthday or anniversary hashes from this source for a certain period.
makeSearch ( array $criteria, string $search_type, array $strict, boolean $match_begin = false, array $custom_strict = [] ) : array	Takes a hash of Turba key => search value and return a (possibly nested) array, using backend attribute names, that can be turned into a search by the driver. The translation is based on the contents of $this->map, and includes nested OR searches for composite fields.
removeUserData ( string $user )	Remove all entries owned by the specified user.
save ( Turba_Object $object ) : string	Modifies an existing entry in the contact source.
search ( array $search_criteria, string $sort_order = null, string $search_type = 'AND', array $return_fields = [], array $custom_strict = [], boolean $match_begin = false, boolean $count_only = false ) : mixed	Searches the source based on the provided criteria.
searchDuplicates ( ) : array	Searches the current address book for duplicate entries.
setContactOwner ( string $owner )	Override the contactOwner setting for this driver.
setDefaultShare ( string $share )	Runs any actions after setting a new default tasklist.
setSourceName ( string $name )	Override the name setting for this driver.
synchronize ( mixed $token = false )	Synchronize, if needed.
toASContact ( Turba_Object $object, array $options = [] ) : Horde_ActiveSync_Message_Contact	Convert the contact to an ActiveSync contact message
toDriver ( string $attribute ) : string	Translates a single Turba attribute to the driver-specific counterpart. The translation is based on the contents of $this->map. This ignores composite fields.
toDriverKeys ( array $hash ) : array	Translates the keys of the first hash from the generalized Turba attributes to the driver-specific fields. The translation is based on the contents of $this->map.
toHash ( Horde_Icalendar_Vcard $vcard ) : array	Function to convert a Horde_Icalendar_Vcard object into a Turba Object Hash with Turba attributes suitable as a parameter for add().
toTurbaKeys ( array $entry ) : array	Translates a hash from being keyed on driver-specific fields to being keyed on the generalized Turba attributes. The translation is based on the contents of $this->map.
tovCard ( Turba_Object $object, string $version = '2.1', array $fields = null, boolean $skipEmpty = false ) : Horde_Icalendar_Vcard	Exports a given Turba_Object as an iCalendar vCard.

Protected Methods

Method	Description
_add ( array $attributes, array $blob_fields = [], array $date_fields = [] )	Adds the specified contact to the addressbook.
_canAdd ( ) : boolean	Returns ability of the backend to add new contacts.
_delete ( string $object_key, string $object_id )	Deletes the specified contact from the addressbook.
_deleteAll ( ) : array	Deletes all contacts from an address book.
_filterTags ( array $objects, array $tags, Array $sort_order = null ) : Turba_List	Returns a Turba_List object containing $objects filtered by $tags.
_getContactOwner ( ) : string	Return the owner to use when searching or creating contacts in this address book.
_getTimeObjectTurbaListFallback ( Horde_Date $start, Horde_Date $end, string $field ) : Turba_List	Default implementation for obtaining a Turba_List to get TimeObjects out of.
_guessName ( array &$hash )	Helper function for guessing name parts from a single name string.
_hasValEnum ( array $valEnum, string $type ) : boolean	Returns whether a ValEnum entry from a DevInf object contains a certain type.
_init ( )	Initialize the driver.
_makeKey ( array $attributes ) : string	Creates an object key for a new object.
_makeUid ( ) : string	Creates an object UID for a new object.
_read ( string $key, mixed $ids, string $owner, array $fields, array $blobFields = [], array $dateFields = [] ) : array	Reads the given data from the address book and returns the results.
_save ( Turba_Object $object ) : string	Saves the specified object in the SQL database.
_search ( array $criteria, array $fields, array $blobFields = [], boolean $count_only = false ) : array	Searches the address book with the given criteria and returns a filtered list of results. If the criteria parameter is an empty array, all records will be returned.
_toTurbaObjects ( array $objects, array $sort_order = null ) : Turba_List	Takes an array of object hashes and returns a Turba_List containing the correct Turba_Objects

Method Details

__construct() public method

Constructs a new Turba_Driver object.

public __construct ( string $name = '', array $params = [] )
$name	string	Source name
$params	array	Hash containing additional configuration parameters.

_add() protected method

Adds the specified contact to the addressbook.

protected _add ( array $attributes, array $blob_fields = [], array $date_fields = [] )
$attributes	array	The attribute values of the contact.
$blob_fields	array	Fields that represent binary data.
$date_fields	array	Fields that represent dates. @since 4.2.0

_canAdd() protected method

Returns ability of the backend to add new contacts.

protected _canAdd ( ) : boolean
return	boolean	Can backend add?

_delete() protected method

Deletes the specified contact from the addressbook.

protected _delete ( string $object_key, string $object_id )
$object_key	string	TODO
$object_id	string	TODO

_deleteAll() protected method

Deletes all contacts from an address book.

protected _deleteAll ( ) : array
return	array	An array of UIDs that have been deleted.

_filterTags() protected method

Returns a Turba_List object containing $objects filtered by $tags.

protected _filterTags ( array $objects, array $tags, Array $sort_order = null ) : Turba_List
$objects	array	A hash of objects, as returned by self::_search.
$tags	array	An array of tags to filter by.
$sort_order	Array	The sort order to pass to Turba_List::sort.
return	Turba_List	The filtered Turba_List object.

_getContactOwner() protected method

Return the owner to use when searching or creating contacts in this address book.

protected _getContactOwner ( ) : string
return	string	Contact owner.

_getTimeObjectTurbaListFallback() protected method

Default implementation for obtaining a Turba_List to get TimeObjects out of.

protected _getTimeObjectTurbaListFallback ( Horde_Date $start, Horde_Date $end, string $field ) : Turba_List
$start	Horde_Date	The starting date.
$end	Horde_Date	The ending date.
$field	string	The address book field containing the timeObject information (birthday, anniversary).
return	Turba_List	A list of objects.

_guessName() protected method

Helper function for guessing name parts from a single name string.

protected _guessName ( array &$hash )
$hash	array	The attributes array.

_hasValEnum() protected method

Returns whether a ValEnum entry from a DevInf object contains a certain type.

protected _hasValEnum ( array $valEnum, string $type ) : boolean
$valEnum	array	A ValEnum hash.
$type	string	A requested attribute type.
return	boolean	True if $type exists in $valEnum.

_init() protected method

Initialize the driver.

protected _init ( )

_makeKey() protected method

Creates an object key for a new object.

protected _makeKey ( array $attributes ) : string
$attributes	array	The attributes (in driver keys) of the object being added.
return	string	A unique ID for the new object.

_makeUid() protected method

Creates an object UID for a new object.

protected _makeUid ( ) : string
return	string	A unique ID for the new object.

_read() protected method

Reads the given data from the address book and returns the results.

protected _read ( string $key, mixed $ids, string $owner, array $fields, array $blobFields = [], array $dateFields = [] ) : array
$key	string	The primary key field to use.
$ids	mixed	The ids of the contacts to load.
$owner	string	Only return contacts owned by this user.
$fields	array	List of fields to return.
$blobFields	array	Array of fields containing binary data.
$dateFields	array	Array of fields containing date data. @since 4.2.0
return	array	Hash containing the search results.

_save() protected method

Saves the specified object in the SQL database.

protected _save ( Turba_Object $object ) : string
$object	Turba_Object	The object to save
return	string	The object id, possibly updated.

_search() protected method

Searches the address book with the given criteria and returns a filtered list of results. If the criteria parameter is an empty array, all records will be returned.

protected _search ( array $criteria, array $fields, array $blobFields = [], boolean $count_only = false ) : array
$criteria	array	Array containing the search criteria.
$fields	array	List of fields to return.
$blobFields	array	Array of fields containing binary data.
$count_only	boolean	Only return the count of matching entries, not the entries themselves.
return	array	Hash containing the search results.

_toTurbaObjects() protected method

Takes an array of object hashes and returns a Turba_List containing the correct Turba_Objects

protected _toTurbaObjects ( array $objects, array $sort_order = null ) : Turba_List
$objects	array	An array of object hashes (keyed to backend).
$sort_order	array	Array of hashes describing sort fields. Each hash has the following fields: ascending - (boolean) Indicating sort direction. field - (string) Sort field.
return	Turba_List	A list object.

add() public method

Adds a new entry to the contact source.

public add ( array $attributes ) : string
$attributes	array	The attributes of the new object to add.
return	string	The new __key value on success.

canAdd() public method

Returns ability of the backend to add new contacts.

public canAdd ( ) : boolean
return	boolean	Can backend add?

checkDefaultShare() public method

Check if the passed in share is the default share for this source.

public checkDefaultShare ( Horde_Share_Object $share, array $srcconfig ) : boolean
$share	Horde_Share_Object	The share object.
$srcconfig	array	The cfgSource entry for the share.
return	boolean	TODO

count() public method

Returns the number of contacts of the current user in this address book.

public count ( ) : integer
return	integer	The number of contacts that the user owns.

createShare() public method

Creates a new Horde_Share for this source type.

public createShare ( string $share_name, array $params ) : Horde_Share
$share_name	string	The share name
$params	array	The params for the share.
return	Horde_Share	The share object.

delete() public method

Deletes the specified entry from the contact source.

public delete ( string $object_id, boolean $remove_tags = true )
$object_id	string	The ID of the object to delete.
$remove_tags	boolean	Remove tags if true.

deleteAll() public method

Deletes all contacts from an address book.

public deleteAll ( string $sourceName = null )
$sourceName	string	The identifier of the address book to delete. If omitted, will clear the current user's 'default' address book for this source type.

fromASContact() public method

Convert an ActiveSync contact message into a hash suitable for importing via self::add().

public fromASContact ( Horde_ActiveSync_Message_Contact $message ) : array
$message	Horde_ActiveSync_Message_Contact	The contact message object.
return	array	A contact hash.

getBlobs() public method

Returns the attributes that are blob types.

public getBlobs ( ) : array
return	array	List of blob attributes in the array keys.

getContactOwner() public method

Return the owner to use when searching or creating contacts in this address book.

public getContactOwner ( ) : string
return	string	Contact owner.

getCriteria() public method

Returns the criteria available for this source except '__key'.

public getCriteria ( ) : array
return	array	An array containing the criteria.

getDateFields() public method

Returns the attributes that represent dates.

Since: 4.2.0

public getDateFields ( ) : array
return	array	List of date attributes in the array keys.

getFields() public method

Returns all non-composite fields for this source. Useful for importing and exporting data, etc.

public getFields ( ) : array
return	array	The field list.

getName() public method

(This is the key into the cfgSources array)

public getName ( )

getObject() public method

Retrieves one object from the source.

public getObject ( string $objectId ) : Turba_Object
$objectId	string	The unique id of the object to retrieve.
return	Turba_Object	The retrieved object.

getObjects() public method

Retrieves a set of objects from the source.

public getObjects ( array $objectIds ) : array
$objectIds	array	The unique ids of the objects to retrieve.
return	array	The array of retrieved objects (Turba_Objects).

getParams() public method

Returns the current driver's additional parameters.

public getParams ( ) : array
return	array	Hash containing the driver's additional parameters.

getTimeObjectTurbaList() public method

Default implementation for obtaining a Turba_List to get TimeObjects out of.

public getTimeObjectTurbaList ( Horde_Date $start, Horde_Date $end, string $field ) : Turba_List
$start	Horde_Date	The starting date.
$end	Horde_Date	The ending date.
$field	string	The address book field containing the timeObject information (birthday, anniversary).
return	Turba_List	A list of objects.

hasCapability() public method

Checks if this backend has a certain capability.

public hasCapability ( string $capability ) : boolean
$capability	string	The capability to check for.
return	boolean	Supported or not.

hasPermission() public method

Checks if the current user has the requested permissions on this address book.

public hasPermission ( integer $perm ) : boolean
$perm	integer	The permission to check for.
return	boolean	True if the user has permission, otherwise false.

listTimeObjects() public method

Returns a list of birthday or anniversary hashes from this source for a certain period.

public listTimeObjects ( Horde_Date $start, Horde_Date $end, string $category ) : array
$start	Horde_Date	The start date of the valid period.
$end	Horde_Date	The end date of the valid period.
$category	string	The timeObjects category to return.
return	array	A list of timeObject hashes.

makeSearch() public method

Takes a hash of Turba key => search value and return a (possibly nested) array, using backend attribute names, that can be turned into a search by the driver. The translation is based on the contents of $this->map, and includes nested OR searches for composite fields.

public makeSearch ( array $criteria, string $search_type, array $strict, boolean $match_begin = false, array $custom_strict = [] ) : array
$criteria	array	Hash of criteria using Turba keys.
$search_type	string	OR search or AND search?
$strict	array	Fields that must be matched exactly.
$match_begin	boolean	Whether to match only at beginning of words.
$custom_strict	array	Custom set of fields that are to matched exactly, but are glued using $search_type and 'AND' together with $strict fields. Allows an 'OR' search pm a custom set of $strict fields.
return	array	An array of search criteria.

removeUserData() public method

Remove all entries owned by the specified user.

public removeUserData ( string $user )
$user	string	The user's data to remove.

save() public method

Modifies an existing entry in the contact source.

public save ( Turba_Object $object ) : string
$object	Turba_Object	The object to update.
return	string	The object id, possibly updated.

search() public method

Searches the source based on the provided criteria.

public search ( array $search_criteria, string $sort_order = null, string $search_type = 'AND', array $return_fields = [], array $custom_strict = [], boolean $match_begin = false, boolean $count_only = false ) : mixed
$search_criteria	array	Hash containing the search criteria.
$sort_order	string	The requested sort order which is passed to Turba_List::sort().
$search_type	string	Do an AND or an OR search (defaults to AND).
$return_fields	array	A list of fields to return; defaults to all fields.
$custom_strict	array	A list of fields that must match exactly.
$match_begin	boolean	Whether to match only at beginning of words.
$count_only	boolean	Only return the count of matching entries, not the entries themselves.
return	mixed	Turba_List\|integer The sorted, filtered list of search results or the number of matching entries (if $count_only is true).

searchDuplicates() public method

Duplicates are determined by comparing email and name or last name and first name values.

public searchDuplicates ( ) : array
return	array	A hash with the following format: `array('name' => array('John Doe' => Turba_List, ...), ...)`

setContactOwner() public method

Override the contactOwner setting for this driver.

public setContactOwner ( string $owner )
$owner	string	The contact owner.

setDefaultShare() public method

Runs any actions after setting a new default tasklist.

public setDefaultShare ( string $share )
$share	string	The default share ID.

setSourceName() public method

Override the name setting for this driver.

public setSourceName ( string $name )
$name	string	The source name. This is the key into the $cfgSources array.

synchronize() public method

Synchronize, if needed.

public synchronize ( mixed $token = false )
$token	mixed	A value indicating the last synchronization point, if available.

toASContact() public method

Convert the contact to an ActiveSync contact message

public toASContact ( Turba_Object $object, array $options = [] ) : Horde_ActiveSync_Message_Contact
$object	Turba_Object	The turba object to convert
$options	array	Options: - protocolversion: (float) The EAS version to support DEFAULT: 2.5 - bodyprefs: (array) A BODYPREFERENCE array. DEFAULT: none (No body prefs enforced). - truncation: (integer) Truncate event body to this length DEFAULT: none (No truncation). - device: (Horde_ActiveSync_Device) The device object.
return	Horde_ActiveSync_Message_Contact

toDriver() public method

Translates a single Turba attribute to the driver-specific counterpart. The translation is based on the contents of $this->map. This ignores composite fields.

public toDriver ( string $attribute ) : string
$attribute	string	The Turba attribute to translate.
return	string	The driver name for this attribute.

toDriverKeys() public method

Translates the keys of the first hash from the generalized Turba attributes to the driver-specific fields. The translation is based on the contents of $this->map.

public toDriverKeys ( array $hash ) : array
$hash	array	Hash using Turba keys.
return	array	Translated version of $hash.

toHash() public method

Function to convert a Horde_Icalendar_Vcard object into a Turba Object Hash with Turba attributes suitable as a parameter for add().

toTurbaKeys() public method

Translates a hash from being keyed on driver-specific fields to being keyed on the generalized Turba attributes. The translation is based on the contents of $this->map.

public toTurbaKeys ( array $entry ) : array
$entry	array	A hash using driver-specific keys.
return	array	Translated version of $entry.

tovCard() public method

Exports a given Turba_Object as an iCalendar vCard.

public tovCard ( Turba_Object $object, string $version = '2.1', array $fields = null, boolean $skipEmpty = false ) : Horde_Icalendar_Vcard
$object	Turba_Object	Turba_Object.
$version	string	The vcard version to produce.
$fields	array	Hash of field names and Horde_SyncMl_Property properties with the requested fields.
$skipEmpty	boolean	Whether to skip empty fields.
return	Horde_Icalendar_Vcard	A vcard object.

Property Details

$_asMap protected static property

Mapping of Turba attributes to ActiveSync fields.

protected static array $_asMap
return	array

$_capabilities protected property

What can this backend do?

protected array $_capabilities
return	array

$_contact_owner protected property

Hold the value for the owner of this address book.

protected string $_contact_owner
return	string

$_count protected property

Number of contacts in this source.

protected int $_count
return	integer

$_name protected property

The internal name of this source.

protected string $_name
return	string

$_objectOptions protected property

Any additional options passed to Turba_Object constructors.

protected array $_objectOptions
return	array

$_params protected property

Hash holding the driver's additional parameters.

protected array $_params
return	array

$alternativeName public property

The name of a field to use as an alternative to the name field if that one is empty.

public string $alternativeName
return	string

$approximate public property

Array of fields to search "approximately" (@see config/backends.php).

public array $approximate
return	array

$fields public property

List of all fields that can be accessed in the backend (excludes composite attributes, etc.).

public array $fields
return	array

$listNameField public property

The name of a field to store contact list names in if not the default.

public string $listNameField
return	string

$map public property

Hash describing the mapping between Turba attributes and driver-specific fields.

public array $map
return	array

$strict public property

Array of fields that must match exactly.

public array $strict
return	array

$tabs public property

Hash with all tabs and their fields.

public array $tabs
return	array

$title public property

The symbolic title of this source.

public string $title
return	string

public toHash ( Horde_Icalendar_Vcard $vcard ) : array
$vcard	Horde_Icalendar_Vcard	The Horde_Icalendar_Vcard object to parse.
return	array	A Turba attribute hash.