\Turba_Driver_Ldap

Turba directory driver implementation for PHP's LDAP extension.

Copyright 2010-2017 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.

Summary

Methods
Properties
Constants
__construct()
getParams()
hasCapability()
getBlobs()
getDateFields()
toDriverKeys()
makeSearch()
toDriver()
toTurbaKeys()
search()
searchDuplicates()
listTimeObjects()
getTimeObjectTurbaList()
getObjects()
getObject()
add()
canAdd()
delete()
deleteAll()
save()
getCriteria()
getFields()
tovCard()
toHash()
toASContact()
fromASContact()
hasPermission()
getName()
getContactOwner()
setContactOwner()
setSourceName()
createShare()
setDefaultShare()
removeUserData()
checkDefaultShare()
count()
synchronize()
$title
$map
$tabs
$fields
$strict
$approximate
$listNameField
$alternativeName
No constants found
_filterTags()
_toTurbaObjects()
_getTimeObjectTurbaListFallback()
_canAdd()
_deleteAll()
_hasValEnum()
_parseName()
_getContactOwner()
_makeKey()
_makeUid()
_init()
_search()
_read()
_add()
_delete()
_save()
_guessName()
_connect()
_makeRDN()
_makeRDNhelper()
_buildSearchQuery()
_getResults()
_emptyAttributeFilter()
_encodeAttributes()
_checkRequiredAttributes()
_isString()
_isPostalAddress()
_getSyntax()
_convertParameters()
$_name
$_params
$_capabilities
$_objectOptions
$_count
$_contact_owner
$_asMap
$_ds
$_syntaxCache
N/A
No private methods found
No private properties found
N/A

Properties

$title

$title : string

The symbolic title of this source.

Type

string

$map

$map : array

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

Type

array

$tabs

$tabs : array

Hash with all tabs and their fields.

Type

array

$fields

$fields : array

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

Type

array

$strict

$strict : array

Array of fields that must match exactly.

Type

array

$approximate

$approximate : array

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

Type

array

$listNameField

$listNameField : string

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

Type

string

$alternativeName

$alternativeName : string

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

Type

string

$_name

$_name : string

The internal name of this source.

Type

string

$_params

$_params : array

Hash holding the driver's additional parameters.

Type

array

$_capabilities

$_capabilities : array

What can this backend do?

Type

array

$_objectOptions

$_objectOptions : array

Any additional options passed to Turba_Object constructors.

Type

array

$_count

$_count : integer

Number of contacts in this source.

Type

integer

$_contact_owner

$_contact_owner : string

Hold the value for the owner of this address book.

Type

string

$_asMap

$_asMap : array

Mapping of Turba attributes to ActiveSync fields.

Type

array

$_ds

$_ds : resource

Handle for the current LDAP connection.

Type

resource

$_syntaxCache

$_syntaxCache : array

Cache _getSyntax() calls.

Type

array

Methods

__construct()

__construct(string  $name = '', array  $params = array()) : \Turba_Driver_Ldap

Constructs a new Turba LDAP driver object.

Parameters

string $name

The source name

array $params

Hash containing additional configuration parameters.

Returns

\Turba_Driver_Ldap

getParams()

getParams() : array

Returns the current driver's additional parameters.

Returns

array —

Hash containing the driver's additional parameters.

hasCapability()

hasCapability(string  $capability) : boolean

Checks if this backend has a certain capability.

Parameters

string $capability

The capability to check for.

Returns

boolean —

Supported or not.

getBlobs()

getBlobs() : array

Returns the attributes that are blob types.

Returns

array —

List of blob attributes in the array keys.

getDateFields()

getDateFields() : array

Returns the attributes that represent dates.

Returns

array —

List of date attributes in the array keys.

toDriverKeys()

toDriverKeys(array  $hash) : array

Extends parent function to build composed fields needed for the dn based on the contents of $this->map.

Parameters

array $hash

Hash using Turba keys.

Returns

array —

Translated version of $hash.

makeSearch()

makeSearch(array  $criteria, string  $search_type, array  $strict, boolean  $match_begin = false, array  $custom_strict = array()) : 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.

Parameters

array $criteria

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.

array $custom_strict

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.

Returns

array —

An array of search criteria.

toDriver()

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.

Parameters

string $attribute

The Turba attribute to translate.

Returns

string —

The driver name for this attribute.

toTurbaKeys()

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.

Parameters

array $entry

A hash using driver-specific keys.

Returns

array —

Translated version of $entry.

search()

search(array  $search_criteria, string  $sort_order = null, string  $search_type = 'AND', array  $return_fields = array(), array  $custom_strict = array(), boolean  $match_begin = false, boolean  $count_only = false) : mixed

Searches the source based on the provided criteria.

Parameters

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.

boolean $count_only

Only return the count of matching entries, not the entries themselves.

Throws

\Turba_Exception

Returns

mixed —

Turba_List|integer The sorted, filtered list of search results or the number of matching entries (if $count_only is true).

searchDuplicates()

searchDuplicates() : array

Searches the current address book for duplicate entries.

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

Throws

\Turba_Exception

Returns

array —

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

listTimeObjects()

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.

Parameters

\Horde_Date $start

The start date of the valid period.

\Horde_Date $end

The end date of the valid period.

string $category

The timeObjects category to return.

Throws

\Turba

Exception

Returns

array —

A list of timeObject hashes.

getTimeObjectTurbaList()

getTimeObjectTurbaList(\Horde_Date  $start, \Horde_Date  $end, string  $field) : \Turba_List

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

Parameters

\Horde_Date $start

The starting date.

\Horde_Date $end

The ending date.

string $field

The address book field containing the timeObject information (birthday, anniversary).

Throws

\Turba_Exception

Returns

\Turba_List

A list of objects.

getObjects()

getObjects(array  $objectIds) : array

Retrieves a set of objects from the source.

Parameters

array $objectIds

The unique ids of the objects to retrieve.

Throws

\Turba_Exception
\Horde_Exception_NotFound

Returns

array —

The array of retrieved objects (Turba_Objects).

getObject()

getObject(string  $objectId) : \Turba_Object

Retrieves one object from the source.

Parameters

string $objectId

The unique id of the object to retrieve.

Throws

\Turba_Exception
\Horde_Exception_NotFound

Returns

\Turba_Object

The retrieved object.

add()

add(array  $attributes) : string

Adds a new entry to the contact source.

Parameters

array $attributes

The attributes of the new object to add.

Throws

\Turba_Exception

Returns

string —

The new __key value on success.

canAdd()

canAdd() : boolean

Returns ability of the backend to add new contacts.

Returns

boolean —

Can backend add?

delete()

delete(string  $object_id, boolean  $remove_tags = true) 

Deletes the specified entry from the contact source.

Parameters

string $object_id

The ID of the object to delete.

boolean $remove_tags

Remove tags if true.

Throws

\Turba_Exception
\Horde_Exception_NotFound

deleteAll()

deleteAll(string  $sourceName = null) 

Deletes all contacts from an address book.

Parameters

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.

Throws

\Turba_Exception

save()

save(\Turba_Object  $object) : string

Modifies an existing entry in the contact source.

Parameters

\Turba_Object $object

The object to update.

Throws

\Turba_Exception

Returns

string —

The object id, possibly updated.

getCriteria()

getCriteria() : array

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

Returns

array —

An array containing the criteria.

getFields()

getFields() : array

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

Returns

array —

The field list.

tovCard()

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.

Parameters

\Turba_Object $object

Turba_Object.

string $version

The vcard version to produce.

array $fields

Hash of field names and Horde_SyncMl_Property properties with the requested fields.

boolean $skipEmpty

Whether to skip empty fields.

Returns

\Horde_Icalendar_Vcard —

A vcard object.

toHash()

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().

Parameters

\Horde_Icalendar_Vcard $vcard

The Horde_Icalendar_Vcard object to parse.

Returns

array —

A Turba attribute hash.

toASContact()

toASContact(\Turba_Object  $object, array  $options = array()) : \Horde_ActiveSync_Message_Contact

Convert the contact to an ActiveSync contact message

Parameters

\Turba_Object $object

The turba object to convert

array $options

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.

Returns

\Horde_ActiveSync_Message_Contact

fromASContact()

fromASContact(\Horde_ActiveSync_Message_Contact  $message) : array

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

Parameters

\Horde_ActiveSync_Message_Contact $message

The contact message object.

Returns

array —

A contact hash.

hasPermission()

hasPermission(integer  $perm) : boolean

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

Parameters

integer $perm

The permission to check for.

Returns

boolean —

True if the user has permission, otherwise false.

getName()

getName() 

Return the name of this address book.

(This is the key into the cfgSources array)

getContactOwner()

getContactOwner() : string

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

Returns

string —

Contact owner.

setContactOwner()

setContactOwner(string  $owner) 

Override the contactOwner setting for this driver.

Parameters

string $owner

The contact owner.

setSourceName()

setSourceName(string  $name) 

Override the name setting for this driver.

Parameters

string $name

The source name. This is the key into the $cfgSources array.

createShare()

createShare(string  $share_name, array  $params) : \Horde_Share

Creates a new Horde_Share for this source type.

Parameters

string $share_name

The share name

array $params

The params for the share.

Returns

\Horde_Share —

The share object.

setDefaultShare()

setDefaultShare(string  $share) 

Runs any actions after setting a new default tasklist.

Parameters

string $share

The default share ID.

removeUserData()

removeUserData(string  $user) 

Remove all entries owned by the specified user.

Parameters

string $user

The user's data to remove.

Throws

\Turba_Exception

checkDefaultShare()

checkDefaultShare(\Horde_Share_Object  $share, array  $srcconfig) : boolean

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

Parameters

\Horde_Share_Object $share

The share object.

array $srcconfig

The cfgSource entry for the share.

Returns

boolean —

TODO

count()

count() : integer

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

Throws

\Turba_Exception

Returns

integer —

The number of contacts that the user owns.

synchronize()

synchronize(mixed  $token = false) 

Synchronize, if needed.

Parameters

mixed $token

A value indicating the last synchronization point, if available.

_filterTags()

_filterTags(array  $objects, array  $tags, Array  $sort_order = null) : \Turba_List

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

Parameters

array $objects

A hash of objects, as returned by self::_search.

array $tags

An array of tags to filter by.

Array $sort_order

The sort order to pass to Turba_List::sort.

Returns

\Turba_List

The filtered Turba_List object.

_toTurbaObjects()

_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

Parameters

array $objects

An array of object hashes (keyed to backend).

array $sort_order

Array of hashes describing sort fields. Each hash has the following fields:

ascending - (boolean) Indicating sort direction.
field - (string) Sort field.

Returns

\Turba_List

A list object.

_getTimeObjectTurbaListFallback()

_getTimeObjectTurbaListFallback(\Horde_Date  $start, \Horde_Date  $end, string  $field) : \Turba_List

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

Parameters

\Horde_Date $start

The starting date.

\Horde_Date $end

The ending date.

string $field

The address book field containing the timeObject information (birthday, anniversary).

Throws

\Turba_Exception

Returns

\Turba_List

A list of objects.

_canAdd()

_canAdd() : boolean

TODO

Returns

boolean —

TODO

_deleteAll()

_deleteAll() : array

Deletes all contacts from an address book.

Throws

\Turba_Exception

Returns

array —

An array of UIDs that have been deleted.

_hasValEnum()

_hasValEnum(array  $valEnum, string  $type) : boolean

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

Parameters

array $valEnum

A ValEnum hash.

string $type

A requested attribute type.

Returns

boolean —

True if $type exists in $valEnum.

_parseName()

_parseName(array  $hash) : array

Checks $hash for the presence of a 'name' attribute. If not found, attempt to build one from other available values.

Parameters

array $hash

A hash of turba attributes.

Returns

array —

Hash of Turba attributes, with the 'name' attribute populated.

_getContactOwner()

_getContactOwner() : string

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

Returns

string —

Contact owner.

_makeKey()

_makeKey(array  $attributes) : string

Build a DN based on a set of attributes and what attributes make a DN for the current source.

Parameters

array $attributes

The attributes (in driver keys) of the object being added.

Returns

string —

The DN for the new object.

_makeUid()

_makeUid() : string

Creates an object UID for a new object.

Returns

string —

A unique ID for the new object.

_init()

_init() 

Initialize the driver.

Throws

\Turba_Exception

_search()

_search(array  $criteria, array  $fields, array  $blobFields = array(), boolean  $count_only = false) : array

Searches the LDAP directory with the given criteria and returns a filtered list of results. If no criteria are specified, all records are returned.

Parameters

array $criteria

Array containing the search criteria.

array $fields

List of fields to return.

array $blobFields

Fields that contain binary data.

boolean $count_only

Only return the count of matching entries, not the entries themselves.

Throws

\Turba_Exception

Returns

array —

Hash containing the search results.

_read()

_read(string  $key, mixed  $ids, string  $owner, array  $fields, array  $blobFields = array(), array  $dateFields = array()) : array

Reads the LDAP directory for a given element and returns the results.

Parameters

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.

array $blobFields

Array of fields containing binary data.

array $dateFields

Array of fields containing date data. @since 4.2.0

Throws

\Horde_Exception_NotFound

Returns

array —

Hash containing the search results.

_add()

_add(array  $attributes, array  $blob_fields = array(), array  $date_fields = array()) 

Adds the specified contact to the addressbook.

Parameters

array $attributes

The attribute values of the contact.

array $blob_fields

Fields that represent binary data.

array $date_fields

Fields that represent dates. @since 4.2.0

Throws

\Turba_Exception

_delete()

_delete(string  $object_key, string  $object_id) 

Deletes the specified entry from the LDAP directory.

Parameters

string $object_key

TODO

string $object_id

TODO

Throws

\Turba_Exception

_save()

_save(\Turba_Object  $object) : string

Modifies the specified entry in the LDAP directory.

Parameters

\Turba_Object $object

The object we wish to save.

Throws

\Turba_Exception

Returns

string —

The object id, possibly updated.

_guessName()

_guessName(array  $hash) 

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

Parameters

array $hash

The attributes array.

_connect()

_connect() 

Initiate LDAP connection.

Not done in __construct(), only when a read or write action is necessary.

_makeRDN()

_makeRDN(array  $attributes) : string

Build a RDN based on a set of attributes and what attributes make a RDN for the current source.

Parameters

array $attributes

The attributes (in driver keys) of the object being added.

Returns

string —

The RDN for the new object.

_makeRDNhelper()

_makeRDNhelper(array  $attributes, array  $dn) : string

Helper function for _makeRDN().

Recursively builds the (possibly nested) attribute-value array to build a DN. Nested arrays will be joined with the '+' character, see Horde_Ldap::quoteDN().

Parameters

array $attributes

The attributes (in driver keys) of the object being added.

array $dn

The array describing how the DN should be built.

Returns

string —

The array to be passed to Horde_Ldap::quoteDN().

_buildSearchQuery()

_buildSearchQuery(array  $criteria) : string

Build a piece of a search query.

Parameters

array $criteria

The array of criteria.

Returns

string —

An LDAP query fragment.

_getResults()

_getResults(array  $fields, resource  $res) : array

Get some results from a result identifier and clean them up.

Parameters

array $fields

List of fields to return.

resource $res

Result identifier.

Throws

\Turba_Exception

Returns

array —

Hash containing the results.

_emptyAttributeFilter()

_emptyAttributeFilter(  $var) : boolean

Remove empty attributes from attributes array.

Parameters

$var

Returns

boolean —

Boolean used by array_filter.

_encodeAttributes()

_encodeAttributes(array  $attributes) 

Format and encode attributes including postal addresses, character set encoding, etc.

Parameters

array $attributes

The attributes array.

_checkRequiredAttributes()

_checkRequiredAttributes(array  $objectclasses) : array

Returns a list of required attributes.

Parameters

array $objectclasses

List of objectclasses that should be checked for required attributes.

Throws

\Turba_Exception

Returns

array —

List of attribute names of the specified objectclasses that have been configured as being required.

_isString()

_isString(string  $attribute) : boolean

Checks if an attribute refers to a string.

Parameters

string $attribute

An attribute name.

Returns

boolean —

True if the specified attribute refers to a string.

_isPostalAddress()

_isPostalAddress(string  $attribute) : boolean

Checks if an attribute refers to a Postal Address.

Parameters

string $attribute

An attribute name.

Returns

boolean —

True if the specified attribute refers to a Postal Address.

_getSyntax()

_getSyntax(string  $att) : string

Returns the syntax of an attribute, if necessary recursively.

Parameters

string $att

Attribute name.

Throws

\Turba_Exception

Returns

string —

Attribute syntax.

_convertParameters()

_convertParameters(array  $in) : array

Converts Turba connection parameter so Horde_Ldap parameters.

Parameters

array $in

Turba parameters.

Returns

array —

Horde_Ldap parameters.