Class Turba_Driver

Description

The Turba_Driver:: class provides a common abstracted interface to the various directory search drivers. It includes functions for searching, adding, removing, and modifying directory entries.

$Horde: turba/lib/Driver.php,v 1.57.2.101 2011-01-17 13:59:05 jan Exp $

Located in /lib/Driver.php (line 13)


	
			
Direct descendents
Class Description
 class Turba_Driver_favourites Read-only Turba directory driver implementation for favourite recipients. Relies on the contacts/favouriteRecipients API method.
 class Turba_Driver_group Read-only Turba_Driver implementation for creating a Horde_Group based address book.
 class Turba_Driver_imsp Turba directory driver implementation for an IMSP server.
 class Turba_Driver_kolab Horde Turba driver for the Kolab IMAP Server.
 class Turba_Driver_ldap Turba directory driver implementation for PHP's LDAP extension.
 class Turba_Driver_null Null Turba directory driver.
 class Turba_Driver_prefs Turba directory driver implementation for Horde Preferences - very simple, lightweight container.
 class Turba_Driver_share The Turba_Driver:: class provides a common abstracted interface to the various directory search drivers. It includes functions for searching, adding, removing, and modifying directory entries.
 class Turba_Driver_vbook Turba directory driver implementation for virtual address books.
 class Turba_Driver_sql Turba directory driver implementation for PHP's PEAR database abstraction layer.
Variable Summary
 array $approximate
 array $fields
 array $map
 string $name
 array $strict
 array $tabs
 string $title
 integer $_count
 array $_params
Method Summary
 Turba_Driver Turba_Driver (array $params)
 mixed add (array $attributes)
 boolean canAdd ()
 boolean checkDefaultShare ( &$share, array $srcconfig, Horde_Share $share)
 integer count ()
 mixed &createShare ( $share_id, array $params)
 void delete (string $object_id)
 mixed deleteAll ([string $sourceName = null])
 string generateUID ()
 array getBlobs ()
 string getContactOwner ()
 string getCountry (string $country)
 array getCriteria ()
 array getFields ()
 void getName ()
 Turba_Object &getObject (string $objectId)
 array &getObjects (array $objectIds)
 array getParams ()
 boolean hasCapability (string $capability)
 boolean hasPermission (integer $perm)
 mixed listTimeObjects (Horde_Date $start, Horde_Date $end, $category $category)
 array makeSearch ( $criteria, string $search_type, array $strict, [boolean $match_begin = false], array $hash)
 mixed removeUserData (string $user)
 string save (Turba_Object $object)
 The &search (array $search_criteria, [string $sort_order = null], [string $search_type = 'AND'], [array $return_fields = array()], [array $custom_strict = array()], [boolean $match_begin = false])
 Turba_Driver &singleton (mixed $name)
 string toDriver (string $attribute)
 array toDriverKeys (array $hash)
 array toHash ( &$vcard, Horde_iCalendar_vcard $vcard)
 array toTurbaKeys (array $entry)
 Horde_iCalendar_vcard tovCard (Turba_Object $object, [string $version = '2.1'], [array $fields = null], [boolean $skipEmpty = false])
 void _add ( $attributes)
 void _canAdd ()
 void _delete ( $object_key,  $object_id)
 mixed _getTimeObjectTurbaList (Horde_Date $start, Horde_Date $end, string $field)
 mixed _getTimeObjectTurbaListFallback (Horde_Date $start, Horde_Date $end, string $field)
 void _init ()
 string _makeKey (array $attributes)
 array _read (string $key, mixed $ids, string $owner, array $fields)
 string _save ( $object_key,  $object_id,  $attributes)
 array _search (array $criteria, array $fields)
 Turba_List _toTurbaObjects (array $objects, [string $sort_order = null])
Variables
string $alternativeName = null (line 80)

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

array $approximate = array() (line 65)

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

array $fields = array() (line 50)

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

string $listNameField = null (line 72)

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

array $map = array() (line 35)

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

string $name (line 20)

The internal name of this source.

array $strict = array() (line 57)

Array of fields that must match exactly.

array $tabs = array() (line 42)

Hash with all tabs and their fields.

string $title (line 27)

The symbolic title of this source.

array $_capabilities = array() (line 94)

What can this backend do?


Redefined in descendants as:
string $_contact_owner = '' (line 108)

Hold the value for the owner of this address book.

integer $_count = null (line 101)

Number of contacts in this source.

array $_params = array() (line 87)

Hash holding the driver's additional parameters.

Methods
Constructor Turba_Driver (line 116)

Constructs a new Turba_Driver object.

Turba_Driver Turba_Driver (array $params)
  • array $params: Hash containing additional configuration parameters.
add (line 766)

Adds a new entry to the contact source.

  • return: The new __key value on success, or a PEAR_Error object on failure.
mixed add (array $attributes)
  • array $attributes: The attributes of the new object to add.
canAdd (line 802)

Returns ability of the backend to add new contacts.

boolean canAdd ()
checkDefaultShare (line 2593)

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

boolean checkDefaultShare ( &$share, array $srcconfig, Horde_Share $share)
  • Horde_Share $share: The share object e
  • array $srcconfig: The cfgSource entry for the share (not used in this method, but a child class may need it).
  • &$share

Redefined in descendants as:
count (line 902)

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

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

Redefined in descendants as:
createShare (line 2373)

Creates a new Horde_Share for this source type.

  • return: The share object or PEAR_Error.
  • since: Turba 2.2
mixed &createShare ( $share_id, array $params)
  • array $params: The params for the share.
  • $share_id

Redefined in descendants as:
delete (line 817)

Deletes the specified entry from the contact source.

void delete (string $object_id)
  • string $object_id: The ID of the object to delete.
deleteAll (line 861)

Deletes all contacts from an address book.

  • return: True on success, PEAR_Error on failure.
mixed deleteAll ([string $sourceName = null])
  • string $sourceName: The identifier of the address book to delete. If omitted, will clear the current user's 'default' address book for this source type.

Redefined in descendants as:
  • Turba_Driver_vbook::deleteAll() : Deletes all contacts from an address book. Not implemented for virtual address books; just returns true so that the address book can be deleted.
generateUID (line 945)

Generates a universal/unique identifier for a contact. This is NOT something that we expect to be able to parse into an addressbook and a contactId.

  • return: A nice unique string (should be 255 chars or less).
string generateUID ()

Redefined in descendants as:
getBlobs (line 148)

Returns the attributes that are blob types.

  • return: List of blob attributes in the array keys.
array getBlobs ()
getContactOwner (line 2352)

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

string getContactOwner ()
getCountry (line 1873)

Returns the (localized) country name.

  • return: The country name or the country code if a name cannot be found.
string getCountry (string $country)
  • string $country: The two-letter country code.
getCriteria (line 920)

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

  • return: An array containing the criteria.
array getCriteria ()
getFields (line 933)

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

  • return: The field list.
array getFields ()
getName (line 2341)

Return the name of this address book.

(This is the key into the cfgSources array)

void getName ()

Redefined in descendants as:
getObject (line 741)

Retrieves one object from the source.

  • return: The retrieved object.
Turba_Object &getObject (string $objectId)
  • string $objectId: The unique id of the object to retrieve.
getObjects (line 694)

Retrieves a set of objects from the source.

  • return: The array of retrieved objects (Turba_Objects).
array &getObjects (array $objectIds)
  • array $objectIds: The unique ids of the objects to retrieve.
getParams (line 126)

Returns the current driver's additional parameters.

  • return: Hash containing the driver's additional parameters.
array getParams ()
hasCapability (line 138)

Checks if this backend has a certain capability.

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

Redefined in descendants as:
hasPermission (line 2322)

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

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

Redefined in descendants as:
listTimeObjects (line 578)

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

  • return: A list of timeObject hashes || PEAR_Error
mixed listTimeObjects (Horde_Date $start, Horde_Date $end, $category $category)
  • Horde_Date $start: The start date of the valid period.
  • Horde_Date $end: The end date of the valid period.
  • $category $category: The timeObjects category to return.
makeSearch (line 271)

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.

  • return: An array of search criteria.
array makeSearch ( $criteria, string $search_type, array $strict, [boolean $match_begin = false], array $hash)
  • array $hash: Hash of criteria using Turba keys.
  • string $search_type: OR search or AND search?
  • array $strict: Fields that must be matched exactly.
  • boolean $match_begin: Whether to match only at beginning of words.
  • $criteria
removeUserData (line 2579)

Remove all entries owned by the specified user.

  • return: True | PEAR_Error
mixed removeUserData (string $user)
  • string $user: The user's data to remove.

Redefined in descendants as:
save (line 877)

Modifies an existing entry in the contact source.

  • return: The object id, possibly updated.
string save (Turba_Object $object)
search (line 471)

Searches the source based on the provided criteria.

  • return: sorted, filtered list of search results.
  • todo: Allow $criteria to contain the comparison operator (<, =, >, 'like') and modify the drivers accordingly.
The &search (array $search_criteria, [string $sort_order = null], [string $search_type = 'AND'], [array $return_fields = array()], [array $custom_strict = array()], [boolean $match_begin = false])
  • array $search_criteria: Hash containing the search criteria.
  • string $sort_order: The requested sort order which is passed to Turba_List::sort().
  • string $search_type: Do an AND or an OR search (defaults to AND).
  • array $return_fields: A list of fields to return; defaults to all fields.
  • array $custom_strict: A list of fields that must match exactly.
  • boolean $match_begin: Whether to match only at beginning of words.
singleton (line 2478)

Attempts to return a reference to a concrete Turba_Driver instance based on the $config array. It will only create a new instance if no Turba_Driver instance with the same parameters currently exists.

This method must be invoked as: $driver = &Turba_Driver::singleton()

  • return: The concrete Turba_Driver reference, or a PEAR_Error on error.
Turba_Driver &singleton (mixed $name)
  • mixed $name: Either a string containing the internal name of this source, or a config array describing the source.
toDriver (line 416)

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

  • return: The driver name for this attribute.
string toDriver (string $attribute)
  • string $attribute: The Turba attribute to translate.
toDriverKeys (line 172)

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.

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

Redefined in descendants as:
toHash (line 1894)

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

array toHash ( &$vcard, Horde_iCalendar_vcard $vcard)
  • Horde_iCalendar_vcard $vcard: The Horde_iCalendar_vcard object to parse.
  • &$vcard
toTurbaKeys (line 438)

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.

  • return: Translated version of $entry.
array toTurbaKeys (array $entry)
  • array $entry: A hash using driver-specific keys.
tovCard (line 963)

Exports a given Turba_Object as an iCalendar vCard.

  • return: A Horde_iCalendar_vcard object.
Horde_iCalendar_vcard tovCard (Turba_Object $object, [string $version = '2.1'], [array $fields = null], [boolean $skipEmpty = false])
  • Turba_Object $object: Turba_Object.
  • string $version: The vcard version to produce.
  • array $fields: Hash of field names and SyncML_Property properties with the requested fields.
  • boolean $skipEmpty: Whether to skip empty fields.
_add (line 2549)

Adds the specified contact to the SQL database.

void _add ( $attributes)
  • $attributes

Redefined in descendants as:
_delete (line 2557)

Deletes the specified contact from the SQL database.

void _delete ( $object_key,  $object_id)
  • $object_key
  • $object_id

Redefined in descendants as:
_getContactOwner (line 2360)
void _getContactOwner ()

Redefined in descendants as:
_getTimeObjectTurbaList (line 663)

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

  • return: A Tubra_List of objects || PEAR_Error
mixed _getTimeObjectTurbaList (Horde_Date $start, Horde_Date $end, string $field)
  • Horde_Date $start: The starting date.
  • Horde_Date $end: The ending date.
  • string $field: The address book field containing the timeObject information (birthday, anniversary)

Redefined in descendants as:
_getTimeObjectTurbaListFallback (line 679)

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

  • return: A Tubra_List of objects || PEAR_Error
mixed _getTimeObjectTurbaListFallback (Horde_Date $start, Horde_Date $end, string $field)
  • Horde_Date $start: The starting date.
  • Horde_Date $end: The ending date.
  • string $field: The address book field containing the timeObject information (birthday, anniversary)
_init (line 2511)

Initialize the driver.

void _init ()

Redefined in descendants as:
_makeKey (line 2391)

Creates an object key for a new object.

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

Redefined in descendants as:
_read (line 2541)

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

  • return: Hash containing the search results.
array _read (string $key, mixed $ids, string $owner, array $fields)
  • string $key: The primary key field to use.
  • mixed $ids: The ids of the contacts to load.
  • string $owner: Only return contacts owned by this user.
  • array $fields: List of fields to return.

Redefined in descendants as:
_save (line 2567)

Saves the specified object in the SQL database.

  • return: The object id, possibly updated.
string _save ( $object_key,  $object_id,  $attributes)
  • $object_key
  • $object_id
  • $attributes

Redefined in descendants as:
_search (line 2526)

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.

  • return: Hash containing the search results.
array _search (array $criteria, array $fields)
  • array $criteria: Array containing the search criteria.
  • array $fields: List of fields to return.

Redefined in descendants as:
  • Turba_Driver_favourites::_search() : Searches the favourites list with the given criteria and returns a filtered list of results. If the criteria parameter is an empty array, all records will be returned.
  • Turba_Driver_group::_search() : Searches the group list with the given criteria and returns a filtered list of results. If the criteria parameter is an empty array, all records will be returned.
  • Turba_Driver_imsp::_search() : Returns all entries matching $critera.
  • Turba_Driver_kolab::_search() : Searches the Kolab message store with the given criteria and returns a filtered list of results. If the criteria parameter is an empty array, all records will be returned.
  • Turba_Driver_ldap::_search() : Searches the LDAP directory with the given criteria and returns a filtered list of results. If no criteria are specified, all records are returned.
  • Turba_Driver_null::_search()
  • Turba_Driver_prefs::_search() : Returns all entries - searching isn't implemented here for now. The parameters are simply ignored.
  • Turba_Driver_share::_search() : 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.
  • Turba_Driver_vbook::_search() : Return all entries matching the combined searches represented by $criteria and the vitural address book's search criteria.
  • Turba_Driver_sql::_search() : Searches the SQL database 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 (line 537)

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

  • return: containing requested Turba_Objects
Turba_List _toTurbaObjects (array $objects, [string $sort_order = null])
  • array $objects: An array of object hashes (keyed to backend).
  • string $sort_order: Desired sort order to pass to Turba_List::sort()

Documentation generated on Sun, 30 Jan 2011 05:39:22 +0000 by phpDocumentor 1.4.3