Documentation

Turba_Driver_Vbook extends Turba_Driver
in package

Turba

Turba directory driver implementation for virtual address books.

See the enclosed file LICENSE for license information (ASL). If you did not receive this file, see http://www.horde.org/licenses/apache.

$alternativeName

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


    public
        string
    $alternativeName
     = \null

$approximate

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


    public
        array<string|int, mixed>
    $approximate
     = array()

$fields

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


    public
        array<string|int, mixed>
    $fields
     = array()

$listNameField

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


    public
        string
    $listNameField
     = \null

$map

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


    public
        array<string|int, mixed>
    $map
     = array()

$searchCriteria

The search criteria that defines this virtual address book.


    public
        array<string|int, mixed>
    $searchCriteria

$searchType

Search type for this virtual address book.


    public
        string
    $searchType

$strict

Array of fields that must match exactly.


    public
        array<string|int, mixed>
    $strict
     = array()

$tabs

Hash with all tabs and their fields.


    public
        array<string|int, mixed>
    $tabs
     = array()

$title

The symbolic title of this source.


    public
        string
    $title

$_asMap

Mapping of Turba attributes to ActiveSync fields.


    protected
    static    array<string|int, mixed>
    $_asMap
     = array('name' => 'fileas', 'lastname' => 'lastname', 'firstname' => 'firstname', 'middlenames' => 'middlename', 'nickname' => 'nickname', 'namePrefix' => 'title', 'nameSuffix' => 'suffix', 'homeStreet' => 'homestreet', 'homeCity' => 'homecity', 'homeProvince' => 'homestate', 'homePostalCode' => 'homepostalcode', 'homeCountryFree' => 'homecountry', 'otherStreet' => 'otherstreet', 'otherCity' => 'othercity', 'otherProvince' => 'otherstate', 'otherPostalCode' => 'otherpostalcode', 'otherCountryFree' => 'othercountry', 'workStreet' => 'businessstreet', 'workCity' => 'businesscity', 'workProvince' => 'businessstate', 'workPostalCode' => 'businesspostalcode', 'workCountryFree' => 'businesscountry', 'title' => 'jobtitle', 'company' => 'companyname', 'department' => 'department', 'office' => 'officelocation', 'spouse' => 'spouse', 'website' => 'webpage', 'assistant' => 'assistantname', 'manager' => 'managername', 'yomifirstname' => 'yomifirstname', 'yomilastname' => 'yomilastname', 'imaddress' => 'imaddress', 'imaddress2' => 'imaddress2', 'imaddress3' => 'imaddress3', 'homePhone' => 'homephonenumber', 'homePhone2' => 'home2phonenumber', 'workPhone' => 'businessphonenumber', 'workPhone2' => 'business2phonenumber', 'fax' => 'businessfaxnumber', 'homeFax' => 'homefaxnumber', 'pager' => 'pagernumber', 'cellPhone' => 'mobilephonenumber', 'carPhone' => 'carphonenumber', 'assistPhone' => 'assistnamephonenumber', 'companyPhone' => 'companymainphone', 'radioPhone' => 'radiophonenumber')

$_capabilities

What can this backend do?


    protected
        array<string|int, mixed>
    $_capabilities
     = array()

$_contact_owner

Hold the value for the owner of this address book.


    protected
        string
    $_contact_owner
     = ''

$_count

Number of contacts in this source.


    protected
        int
    $_count
     = \null

$_driver

The composed driver.


    protected
        Turba_Driver
    $_driver

$_name

The internal name of this source.


    protected
        string
    $_name

$_objectOptions

Any additional options passed to Turba_Object constructors.


    protected
        array<string|int, mixed>
    $_objectOptions
     = array()

$_params

Hash holding the driver's additional parameters.


    protected
        array<string|int, mixed>
    $_params
     = array()

$_share


    protected
        mixed
    $_share

__construct()

Constructs a new Turba_Driver object.


    public
                    __construct([string $name = '' ][, array<string|int, mixed> $params = array() ]) : mixed

Parameters

$name : string = ''

Source name

$params : array<string|int, mixed> = array()

Additional configuration parameters:

share: Horde_Share object representing this vbook.
source: The configuration array of the parent source or the source name of parent source in the global cfgSources array.

Return values

mixed —

add()

Adds a new entry to the contact source.


    public
                    add(array<string|int, mixed> $attributes) : string

Parameters

$attributes : array<string|int, mixed>: The attributes of the new object to add.

Return values

string —

The new __key value on success.

canAdd()

Returns ability of the backend to add new contacts.


    public
                    canAdd() : bool

Return values

bool —

Can backend add?

checkDefaultShare()

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


    public
                    checkDefaultShare(Horde_Share_Object $share, array<string|int, mixed> $srcconfig) : bool

Parameters

$share : Horde_Share_Object: The share object.
$srcconfig : array<string|int, mixed>: The cfgSource entry for the share.

Return values

bool —

TODO

count()

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


    public
                    count() : int

Return values

int —

The number of contacts that the user owns.

createShare()

Creates a new Horde_Share for this source type.


    public
                    createShare(string $share_name, array<string|int, mixed> $params) : Horde_Share

Parameters

$share_name : string: The share name
$params : array<string|int, mixed>: The params for the share.

Return values

Horde_Share —

The share object.

delete()

Deletes the specified entry from the contact source.


    public
                    delete(string $object_id[, bool $remove_tags = true ]) : mixed

Parameters

$object_id : string: The ID of the object to delete.
$remove_tags : bool = true: Remove tags if true.

Return values

mixed —

deleteAll()

Deletes all contacts from an address book.


    public
                    deleteAll([string $sourceName = null ]) : mixed

Parameters

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

Return values

mixed —

fromASContact()

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


    public
                    fromASContact(Horde_ActiveSync_Message_Contact $message) : array<string|int, mixed>

Parameters

$message : Horde_ActiveSync_Message_Contact: The contact message object.

Return values

array<string|int, mixed> —

A contact hash.

getBlobs()

Returns the attributes that are blob types.


    public
                    getBlobs() : array<string|int, mixed>

Return values

array<string|int, mixed> —

List of blob attributes in the array keys.

getContactOwner()

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


    public
                    getContactOwner() : string

Return values

string —

Contact owner.

getCriteria()

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


    public
                    getCriteria() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array containing the criteria.

getDateFields()

Returns the attributes that represent dates.


    public
                    getDateFields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

List of date attributes in the array keys.

getFields()

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


    public
                    getFields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

The field list.

getName()

Return the name of this address book.


    public
                    getName() : mixed

(This is the key into the cfgSources array)

Return values

mixed —

getObject()

Retrieves one object from the source.


    public
                    getObject(string $objectId) : Turba_Object

Parameters

$objectId : string: The unique id of the object to retrieve.

Return values

Turba_Object —

The retrieved object.

getObjects()

Retrieves a set of objects from the source.


    public
                    getObjects(array<string|int, mixed> $objectIds) : array<string|int, mixed>

Parameters

$objectIds : array<string|int, mixed>: The unique ids of the objects to retrieve.

Return values

array<string|int, mixed> —

The array of retrieved objects (Turba_Objects).

getParams()

Returns the current driver's additional parameters.


    public
                    getParams() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Hash containing the driver's additional parameters.

getTimeObjectTurbaList()

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


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

Parameters

$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 values

Turba_List —

A list of objects.

hasCapability()

Checks if this backend has a certain capability.


    public
                    hasCapability(string $capability) : bool

Parameters

$capability : string: The capability to check for.

Return values

bool —

Supported or not.

hasPermission()

Check to see if the currently logged in user has requested permissions.


    public
                    hasPermission(int $perm) : bool

Parameters

$perm : int: The permissions to check against.

Return values

bool —

True or False.

listTimeObjects()

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

Parameters

$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 values

array<string|int, mixed> —

A list of timeObject hashes.

makeSearch()

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<string|int, mixed> $criteria, string $search_type, array<string|int, mixed> $strict[, bool $match_begin = false ][, array<string|int, mixed> $custom_strict = array() ]) : array<string|int, mixed>

Parameters

$criteria : array<string|int, mixed>: Hash of criteria using Turba keys.
$search_type : string: OR search or AND search?
$strict : array<string|int, mixed>: Fields that must be matched exactly.
$match_begin : bool = false: Whether to match only at beginning of words.
$custom_strict : array<string|int, mixed> = 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 values

array<string|int, mixed> —

An array of search criteria.

removeUserData()

Remove all data for a specific user.


    public
                    removeUserData(string $user) : mixed

Parameters

$user : string: The user to remove all data for.

Return values

mixed —

save()

Modifies an existing entry in the contact source.


    public
                    save(Turba_Object $object) : string

Parameters

$object : Turba_Object: The object to update.

Return values

string —

The object id, possibly updated.

search()

Searches the source based on the provided criteria.


    public
                    search(array<string|int, mixed> $search_criteria[, string $sort_order = null ][, string $search_type = 'AND' ][, array<string|int, mixed> $return_fields = array() ][, array<string|int, mixed> $custom_strict = array() ][, bool $match_begin = false ][, bool $count_only = false ]) : mixed

Parameters

$search_criteria : array<string|int, mixed>: Hash containing the search criteria.
$sort_order : string = null: The requested sort order which is passed to Turba_List::sort().
$search_type : string = 'AND': Do an AND or an OR search (defaults to AND).
$return_fields : array<string|int, mixed> = array(): A list of fields to return; defaults to all fields.
$custom_strict : array<string|int, mixed> = array(): A list of fields that must match exactly.
$match_begin : bool = false: Whether to match only at beginning of words.
$count_only : bool = false: Only return the count of matching entries, not the entries themselves.

Return values

mixed —

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

searchDuplicates()

Searches the current address book for duplicate entries.


    public
                    searchDuplicates() : array<string|int, mixed>

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

Return values

array<string|int, mixed> —

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

setContactOwner()

Override the contactOwner setting for this driver.


    public
                    setContactOwner(string $owner) : mixed

Parameters

$owner : string: The contact owner.

Return values

mixed —

setDefaultShare()

Runs any actions after setting a new default tasklist.


    public
                    setDefaultShare(string $share) : mixed

Parameters

$share : string: The default share ID.

Return values

mixed —

setSourceName()

Override the name setting for this driver.


    public
                    setSourceName(string $name) : mixed

Parameters

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

Return values

mixed —

synchronize()

Synchronize, if needed.


    public
                    synchronize([mixed $token = false ]) : mixed

Parameters

$token : mixed = false: A value indicating the last synchronization point, if available.

Return values

mixed —

toASContact()

Convert the contact to an ActiveSync contact message


    public
                    toASContact(Turba_Object $object[, array<string|int, mixed> $options = array() ]) : Horde_ActiveSync_Message_Contact

Parameters

$object : Turba_Object

The turba object to convert

$options : array<string|int, mixed> = 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 values

Horde_ActiveSync_Message_Contact —

toDriver()

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

Parameters

$attribute : string: The Turba attribute to translate.

Return values

string —

The driver name for this attribute.

toDriverKeys()

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<string|int, mixed> $hash) : array<string|int, mixed>

Parameters

$hash : array<string|int, mixed>: Hash using Turba keys.

Return values

array<string|int, mixed> —

Translated version of $hash.

toHash()

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


    public
                    toHash(Horde_Icalendar_Vcard $vcard) : array<string|int, mixed>

Parameters

$vcard : Horde_Icalendar_Vcard: The Horde_Icalendar_Vcard object to parse.

Return values

array<string|int, mixed> —

A Turba attribute hash.

toTurbaKeys()

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<string|int, mixed> $entry) : array<string|int, mixed>

Parameters

$entry : array<string|int, mixed>: A hash using driver-specific keys.

Return values

array<string|int, mixed> —

Translated version of $entry.

tovCard()

Exports a given Turba_Object as an iCalendar vCard.


    public
                    tovCard(Turba_Object $object[, string $version = '2.1' ][, array<string|int, mixed> $fields = null ][, bool $skipEmpty = false ]) : Horde_Icalendar_Vcard

Parameters

$object : Turba_Object: Turba_Object.
$version : string = '2.1': The vcard version to produce.
$fields : array<string|int, mixed> = null: Hash of field names and Horde_SyncMl_Property properties with the requested fields.
$skipEmpty : bool = false: Whether to skip empty fields.

Return values

Horde_Icalendar_Vcard —

A vcard object.

_add()

Adds the specified contact to the addressbook.


    protected
                    _add(array<string|int, mixed> $attributes[, array<string|int, mixed> $blob_fields = array() ][, array<string|int, mixed> $date_fields = array() ]) : mixed

Parameters

$attributes : array<string|int, mixed>: The attribute values of the contact.
$blob_fields : array<string|int, mixed> = array(): Fields that represent binary data.
$date_fields : array<string|int, mixed> = array(): Fields that represent dates. @since 4.2.0

Return values

mixed —

_canAdd()

Returns ability of the backend to add new contacts.


    protected
                    _canAdd() : bool

Return values

bool —

Can backend add?

_delete()

Not supported for virtual address books.


    protected
                    _delete(mixed $object_key, mixed $object_id) : mixed

Parameters

$object_key : mixed: TODO
$object_id : mixed: TODO

Return values

mixed —

_deleteAll()

Deletes all contacts from an address book.


    protected
                    _deleteAll() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of UIDs that have been deleted.

_filterTags()

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


    protected
                    _filterTags(array<string|int, mixed> $objects, array<string|int, mixed> $tags[, array<string|int, mixed> $sort_order = null ]) : Turba_List

Parameters

$objects : array<string|int, mixed>: A hash of objects, as returned by self::_search.
$tags : array<string|int, mixed>: An array of tags to filter by.
$sort_order : array<string|int, mixed> = null: The sort order to pass to Turba_List::sort. (Unused).

Return values

Turba_List —

The filtered Turba_List object.

_getContactOwner()

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


    protected
                    _getContactOwner() : string

Return values

string —

_getTimeObjectTurbaListFallback()

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


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

Parameters

$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 values

Turba_List —

A list of objects.

_guessName()

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


    protected
                    _guessName(array<string|int, mixed> &$hash) : mixed

Parameters

$hash : array<string|int, mixed>: The attributes array.

Return values

mixed —

_hasValEnum()

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


    protected
                    _hasValEnum(array<string|int, mixed> $valEnum, string $type) : bool

Parameters

$valEnum : array<string|int, mixed>: A ValEnum hash.
$type : string: A requested attribute type.

Return values

bool —

True if $type exists in $valEnum.

_init()

Initialize the driver.


    protected
                    _init() : mixed

Return values

mixed —

_makeKey()

Creates an object key for a new object.


    protected
                    _makeKey(array<string|int, mixed> $attributes) : string

Parameters

$attributes : array<string|int, mixed>: The attributes (in driver keys) of the object being added.

Return values

string —

A unique ID for the new object.

_makeUid()

Creates an object UID for a new object.


    protected
                    _makeUid() : string

Return values

string —

A unique ID for the new object.

_parseName()

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


    protected
                    _parseName(array<string|int, mixed> $hash) : array<string|int, mixed>

Parameters

$hash : array<string|int, mixed>: A hash of turba attributes.

Return values

array<string|int, mixed> —

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

_read()

Reads the requested entries from the underlying source.


    protected
                    _read(string $key, mixed $ids, string $owner, array<string|int, mixed> $fields[, array<string|int, mixed> $blobFields = array() ][, array<string|int, mixed> $dateFields = array() ]) : array<string|int, mixed>

Parameters

$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<string|int, mixed>: List of fields to return.
$blobFields : array<string|int, mixed> = array(): Array of fields containing binary data.
$dateFields : array<string|int, mixed> = array(): Array of fields containing date data. @since 4.2.0

Return values

array<string|int, mixed> —

Hash containing the search results.

_save()

Saves the specified object in the SQL database.


    protected
                    _save(Turba_Object $object) : string

Parameters

$object : Turba_Object: The object to save

Return values

string —

The object id, possibly updated.

_search()

Return all entries matching the combined searches represented by $criteria and the vitural address book's search criteria.


    protected
                    _search(array<string|int, mixed> $criteria, array<string|int, mixed> $fields[, array<string|int, mixed> $blobFields = array() ][, mixed $count_only = false ]) : array<string|int, mixed>

Parameters

$criteria : array<string|int, mixed>: Array containing the search criteria.
$fields : array<string|int, mixed>: List of fields to return
$blobFields : array<string|int, mixed> = array(): Array of fields containing binary data.
$count_only : mixed = false: Only return the count of matching entries, not the entries themselves.

Return values

array<string|int, mixed> —

Hash containing the search results.

_toTurbaObjects()

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


    protected
                    _toTurbaObjects(array<string|int, mixed> $objects[, array<string|int, mixed> $sort_order = null ]) : Turba_List

Parameters

$objects : array<string|int, mixed>

An array of object hashes (keyed to backend).

$sort_order : array<string|int, mixed> = null

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

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

Return values

Turba_List —

A list object.

Turba_Driver_Vbook extends Turba_Driver in package Turba

Tags

Table of Contents

Properties

$alternativeName

$approximate

$fields

$listNameField

$map

$searchCriteria

$searchType

$strict

$tabs

$title

$_asMap

$_capabilities

$_contact_owner

$_count

$_driver

$_name

$_objectOptions

$_params

$_share

Methods

__construct()

Parameters

Return values

add()

Parameters

Tags

Return values

canAdd()

Return values

checkDefaultShare()

Parameters

Return values

count()

Tags

Return values

createShare()

Parameters

Return values

delete()

Parameters

Tags

Return values

deleteAll()

Parameters

Tags

Return values

fromASContact()

Parameters

Return values

getBlobs()

Return values

getContactOwner()

Return values

getCriteria()

Return values

getDateFields()

Tags

Return values

getFields()

Return values

getName()

Tags

Return values

getObject()

Parameters

Tags

Return values

getObjects()

Parameters

Tags

Return values

getParams()

Return values

getTimeObjectTurbaList()

Parameters

Tags

Turba_Driver_Vbook extends Turba_Driver
in package

Turba