Class Horde_DataTree

The Horde_DataTree class provides a common abstracted interface into the various backends for the Horde DataTree system.

A piece of data is just a title that is saved in the page for the null driver or can be saved in a database to be accessed from everywhere. Every stored object must have a different name (inside each groupid).

Required values for $params:

'group' -- Define each group of objects we want to build.

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

Direct known subclasses

Horde_DataTree_Null, Horde_DataTree_Sql

Package: DataTree
Author: Stephane Huther shuther1@free.fr
Author: Chuck Hagenbuch chuck@horde.org
Located at Horde/DataTree.php

Methods summary
`public`	# `__construct( array $params = array() )` Constructor. Constructor. Parameters `$params` <p>A hash containing any additional configuration or connection parameters a subclass might need. We always need 'group', a string that defines the prefix for each set of hierarchical data.</p>
`public mixed`	# `getParam( string $param )` Returns a parameter of this Horde_DataTree instance. Returns a parameter of this Horde_DataTree instance. Parameters `$param` The parameter to return. Returns `mixed` The parameter's value or null if it doesn't exist.
`public TODO`	# `remove( string $object, boolean $force = false )` Removes an object. Removes an object. Parameters `$object` The object to remove. `$force` Force removal of every child object? Returns `TODO`
`public TODO`	# `removeUserData( string $user )` Removes all Horde_DataTree objects owned by a certain user. Removes all Horde_DataTree objects owned by a certain user. Parameters `$user` A user name. Returns `TODO`
`public mixed`	# `move( mixed $object, string $newparent = null )` Move an object to a new parent. Move an object to a new parent. Parameters `$object` The object to move. `$newparent` The new parent object. Defaults to the root. Returns `mixed` True on success, PEAR_Error on error.
`public mixed`	# `rename( mixed $old_object, string $new_object_name )` Change an object's name. Change an object's name. Parameters `$old_object` The old object. `$new_object_name` The new object name. Returns `mixed` True on success, PEAR_Error on error.
`public TODO`	# `reorder( string $parents, mixed $order = null, integer $cid = null )` Changes the order of the children of an object. Changes the order of the children of an object. Parameters `$parents` $parent The full id path of the parent object. `$order` <p>If an array it specifies the new positions for all child objects. If an integer and $cid is specified, the position where the child specified by $cid is inserted. If $cid is not specified, the position gets deleted, causing the following positions to shift up.</p> `$cid` See $order. Returns `TODO`
`public`	# `_reorder( string $pid, mixed $order = null, integer $cid = null )` Change order of children of an object. Change order of children of an object. Parameters `$pid` The parent object id string path. `$order` <p>Specific new order position or an array containing the new positions for the given parent.</p> `$cid` <p>If provided indicates insertion of a new child to the parent to avoid incrementing it when shifting up all other children's order. If not provided indicates deletion, so shift all other positions down one.</p>
`public TODO`	# `setOrder( integer $id, integer $order )` Explicitly set the order for a Horde_DataTree object. Explicitly set the order for a Horde_DataTree object. Parameters `$id` The Horde_DataTree object id to change. `$order` The new order. Returns `TODO`
`public TODO`	# `_defineObjectClass( array $attributes )` Dynamically determines the object class. Dynamically determines the object class. Parameters `$attributes` <p>The set of attributes that contain the class information. Defaults to Horde_DataTreeObject.</p> Returns `TODO`
`public TODO &`	# `getObject( string $object, string $class = 'Horde_DataTreeObject' )` Returns a Horde_DataTreeObject (or subclass) object of the data in the object defined by $object. Returns a Horde_DataTreeObject (or subclass) object of the data in the object defined by $object. Parameters `$object` The object to fetch: 'parent:sub-parent:name'. `$class` <p>Subclass of Horde_DataTreeObject to use. Defaults to Horde_DataTreeObject. Null forces the driver to look into the attributes table to determine the subclass to use. If none is found it uses Horde_DataTreeObject.</p> Returns `TODO`
`public TODO &`	# `getObjectById( integer $id, string $class = 'Horde_DataTreeObject' )` Returns a Horde_DataTreeObject (or subclass) object of the data in the object with the ID $id. Returns a Horde_DataTreeObject (or subclass) object of the data in the object with the ID $id. Parameters `$id` An object id. `$class` <p>Subclass of Horde_DataTreeObject to use. Defaults to Horde_DataTreeObject. Null forces the driver to look into the attributes table to determine the subclass to use. If none is found it uses Horde_DataTreeObject.</p> Returns `TODO`
`public &`	# `_getObject( mixed $id, mixed $name, mixed $class )` Helper function for getObject() and getObjectById(). Helper function for getObject() and getObjectById().
`public TODO &`	# `getObjects( array $ids, string $class = 'Horde_DataTreeObject' )` Returns an array of Horde_DataTreeObject (or subclass) objects corresponding to the objects in $ids, with the object names as the keys of the array. Returns an array of Horde_DataTreeObject (or subclass) objects corresponding to the objects in $ids, with the object names as the keys of the array. Parameters `$ids` An array of object ids. `$class` <p>Subclass of Horde_DataTreeObject to use. Defaults to Horde_DataTreeObject. Null forces the driver to look into the attributes table to determine the subclass to use. If none is found it uses Horde_DataTreeObject.</p> Returns `TODO`
`public mixed`	# `get( constant $format, string $startleaf = DATATREE_ROOT, boolean $reload = false, string $rootname = DATATREE_ROOT, integer $maxdepth = -1, boolean $loadTree = false, string $sortby_name = null, string $sortby_key = null, integer $direction = 0 )` Export a list of objects. Export a list of objects. Parameters `$format` Format of the export `$startleaf` <p>The name of the leaf from which we start the export tree.</p> `$reload` <p>Re-load the requested chunk? Defaults to false (only what is currently loaded).</p> `$rootname` <p>The label to use for the root element. Defaults to DATATREE_ROOT.</p> `$maxdepth` <p>The maximum number of levels to return. Defaults to DATATREE_ROOT, which is no limit.</p> `$loadTree` <p>Load a tree starting at $root, or just the requested level and direct parents? Defaults to single level.</p> `$sortby_name` Attribute name to use for sorting. `$sortby_key` Attribute key to use for sorting. `$direction` <p>Sort direction: 0 - ascending 1 - descending</p> Returns `mixed` The tree representation of the objects, or a PEAR_Error on failure.
`public integer`	# `count( string $startleaf = DATATREE_ROOT )` Counts objects. Counts objects. Parameters `$startleaf` <p>The name of the leaf from which we start counting.</p> Returns `integer` The number of the objects below $startleaf.
`public string`	# `sortHash( string $root, string $sortby_name = null, string $sortby_key = null, integer $direction = 0 )` Create attribute sort hash Create attribute sort hash Parameters `$root` <p>The name of the leaf from which we start the export tree.</p> `$sortby_name` Attribute name to use for sorting. `$sortby_key` Attribute key to use for sorting. `$direction` <p>Sort direction: 0 - ascending 1 - descending</p> Returns `string` The sort hash.
`public mixed`	# `getById( constant $format, string $startleaf = DATATREE_ROOT, boolean $reload = false, string $rootname = DATATREE_ROOT, integer $maxdepth = -1 )` Export a list of objects just like get() above, but uses an object id to fetch the list of objects. Export a list of objects just like get() above, but uses an object id to fetch the list of objects. Parameters `$format` Format of the export. `$startleaf` <p>The id of the leaf from which we start the export tree.</p> `$reload` <p>Reload the requested chunk? Defaults to false (only what is currently loaded).</p> `$rootname` <p>The label to use for the root element. Defaults to DATATREE_ROOT.</p> `$maxdepth` <p>The maximum number of levels to return Defaults to -1, which is no limit.</p> Returns `mixed` The tree representation of the objects, or a PEAR_Error on failure.
`public mixed`	# `getGroups( )` Returns a list of all groups (root nodes) of the data tree. Returns a list of all groups (root nodes) of the data tree. Returns `mixed` The group IDs or PEAR_Error on error.
`public TODO`	# `getData( integer $cid )` Retrieve data for an object from the datatree_data field. Retrieve data for an object from the datatree_data field. Parameters `$cid` The object id to fetch, or an array of object ids. Returns `TODO`
`public TODO`	# `set( array $data, string $charset = null )` Import a list of objects. Used by drivers to populate the internal $_data array. Import a list of objects. Used by drivers to populate the internal $_data array. Parameters `$data` The data to import. `$charset` The charset to convert the object name from. Returns `TODO`
`public array`	# `_extractOneLevel( string $leaf = DATATREE_ROOT )` Extract one level of data for a parent leaf, sorted first by their order and then by name. This function is a way to get a collection of $leaf's children. Extract one level of data for a parent leaf, sorted first by their order and then by name. This function is a way to get a collection of $leaf's children. Parameters `$leaf` Name of the parent from which to start. Returns `array` TODO
`public TODO`	# `_extractAllLevelTree( array & $out, string $parent = DATATREE_ROOT, integer $maxdepth = -1 )` Extract all levels of data, starting from a given parent leaf in the datatree. Extract all levels of data, starting from a given parent leaf in the datatree. Parameters `$out` <p>This is an iterating function, so $out is passed by reference to contain the result.</p> `$parent` The name of the parent from which to begin. `$maxdepth` Max of levels of depth to check. Returns `TODO` Note If nothing is returned that means there is no child, but don't forget to add the parent if any subsequent operations are required!
`public TODO`	# `_extractAllLevelList( array & $out, string $parent = DATATREE_ROOT, integer $maxdepth = -1 )` Extract all levels of data, starting from any parent in the tree. Extract all levels of data, starting from any parent in the tree. Returned array format: array(parent => array(child => true)) Parameters `$out` <p>This is an iterating function, so $out is passed by reference to contain the result.</p> `$parent` The name of the parent from which to begin. `$maxdepth` Max number of levels of depth to check. Returns `TODO`
`public mixed`	# `getParent( mixed $child )` Returns a child's direct parent ID. Returns a child's direct parent ID. Parameters `$child` <p>Either the object, an array containing the path elements, or the object name for which to look up the parent's ID.</p> Returns `mixed` The unique ID of the parent or PEAR_Error on error.
`public mixed`	# `getParentById( integer $childId )` Get a $child's direct parent ID. Get a $child's direct parent ID. Parameters `$childId` Get the parent of this object. Returns `mixed` The unique ID of the parent or PEAR_Error on error.
`public mixed`	# `getParents( mixed $child, boolean $getids = false )` Get a list of parents all the way up to the root object for $child. Get a list of parents all the way up to the root object for $child. Parameters `$child` The name of the child `$getids` <p>If true, return parent IDs; otherwise, return names.</p> Returns `mixed` [child] [parent] in a tree format or PEAR_Error.
`public array`	# `getParentList( integer $childId, array $parents = array() )` Get a list of parents all the way up to the root object for $child. Get a list of parents all the way up to the root object for $child. Parameters `$childId` The id of the child. `$parents` The array, as we build it up. Returns `array` A flat list of all of the parents of $child, hashed in $id => $name format.
`public string\|PEAR_Error`	# `getParentIdString( mixed $object )` Get a parent ID string (id:cid format) for the specified object. Get a parent ID string (id:cid format) for the specified object. Parameters `$object` The object to return a parent string for. Returns `string\|PEAR_Error` The ID "path" to the parent object or PEAR_Error on failure.
`public integer`	# `getNumberOfChildren( mixed $parent = DATATREE_ROOT )` Get the number of children an object has, only counting immediate children, not grandchildren, etc. Get the number of children an object has, only counting immediate children, not grandchildren, etc. Parameters `$parent` <p>Either the object or the name for which to count the children, defaults to the root (DATATREE_ROOT).</p> Returns `integer`
`public boolean`	# `exists( mixed $object )` Check if an object exists or not. The root element DATATREE_ROOT always exists. Check if an object exists or not. The root element DATATREE_ROOT always exists. Parameters `$object` The name of the object. Returns `boolean` True if the object exists, false otherwise.
`public string`	# `getName( integer $id )` Get the name of an object from its id. Get the name of an object from its id. Parameters `$id` The id for which to look up the name. Returns `string` TODO
`public string`	# `getId( mixed $name )` Get the id of an object from its name. Get the id of an object from its name. Parameters `$name` <p>Either the object, an array containing the path elements, or the object name for which to look up the id.</p> Returns `string`
`public mixed`	# `getOrder( mixed $child )` Get the order position of an object. Get the order position of an object. Parameters `$child` Either the object or the name. Returns `mixed` The object's order position or a PEAR error on failure.
`public string`	# `encodeName( string $name )` Replace all occurences of ':' in an object name with '.'. Replace all occurences of ':' in an object name with '.'. Parameters `$name` The name of the object. Returns `string` The encoded name.
`public string`	# `getShortName( string $name )` Get the short name of an object, returns only the last portion of the full name. For display purposes only. Get the short name of an object, returns only the last portion of the full name. For display purposes only. Parameters `$name` The name of the object. Returns `string` The object's short name.
`public array`	# `getSortedTree( string $root, boolean $loadTree = false, string $sortby_name = null, string $sortby_key = null, integer $direction = 0 )` Returns a tree sorted by the specified attribute name and/or key. Returns a tree sorted by the specified attribute name and/or key. Parameters `$root` <p>Which portion of the tree to sort. Defaults to all of it.</p> `$loadTree` <p>Sort the tree starting at $root, or just the requested level and direct parents? Defaults to single level.</p> `$sortby_name` Attribute name to use for sorting. `$sortby_key` Attribute key to use for sorting. `$direction` <p>Sort direction: 0 - ascending 1 - descending</p> Returns `array` TODO
`public TODO`	# `add( mixed $object, boolean $id_as_name = false )` Adds an object. Adds an object. Parameters `$object` <p>The object to add (string or Horde_DataTreeObject).</p> `$id_as_name` <p>True or false to indicate if object ID is to be used as object name. Used in situations where there is no available unique input for object name.</p> Returns `TODO`
`public TODO`	# `_add( string $name, integer $id, integer $pid, integer $order = '' )` Add an object. Add an object. Parameters `$name` The short object name. `$id` The new object's unique ID. `$pid` The unique ID of the object's parent. `$order` The ordering data for the object. Returns `TODO` Private
`public array`	# `getAttributes( integer $cid )` Retrieve data for an object from the horde_datatree_attributes table. Retrieve data for an object from the horde_datatree_attributes table. Parameters `$cid` <p>array $cid The object id to fetch, or an array of object ids.</p> Returns `array` A hash of attributes, or a multi-level hash of object ids => their attributes.
`public TODO`	# `countByAttributes( array $criteria, string $parent = DATATREE_ROOT, boolean $allLevels = true, string $restrict = 'name' )` Returns the number of objects matching a set of attribute criteria. Returns the number of objects matching a set of attribute criteria. Parameters `$criteria` The array of criteria. `$parent` The parent node to start searching from. `$allLevels` <p>Return all levels, or just the direct children of $parent? Defaults to all levels.</p> `$restrict` <p>Only return attributes with the same attribute_name or attribute_id.</p> Returns `TODO` See buildAttributeQuery()
`public TODO`	# `getByAttributes( array $criteria, string $parent = DATATREE_ROOT, boolean $allLevels = true, string $restrict = 'name', integer $from = 0, integer $count = 0, string $sortby_name = null, string $sortby_key = null, integer $direction = 0 )` Returns a set of object ids based on a set of attribute criteria. Returns a set of object ids based on a set of attribute criteria. Parameters `$criteria` The array of criteria. `$parent` The parent node to start searching from. `$allLevels` <p>Return all levels, or just the direct children of $parent? Defaults to all levels.</p> `$restrict` <p>Only return attributes with the same attribute_name or attribute_id.</p> `$from` The object to start to fetching `$count` The number of objects to fetch `$sortby_name` Attribute name to use for sorting. `$sortby_key` Attribute key to use for sorting. `$direction` <p>Sort direction: 0 - ascending 1 - descending</p> Returns `TODO` See buildAttributeQuery()
`public array`	# `sortByAttributes( array $unordered_ids, array $sortby_name = null, array $sortby_key = null, array $direction = 0 )` Sorts IDs by attribute values. IDs without attributes will be added to the end of the sorted list. Sorts IDs by attribute values. IDs without attributes will be added to the end of the sorted list. Parameters `$unordered_ids` Array of ids to sort. `$sortby_name` Attribute name to use for sorting. `$sortby_key` Attribute key to use for sorting. `$direction` <p>Sort direction: 0 - ascending 1 - descending</p> Returns `array` Sorted ids.
`public TODO`	# `updateData( Horde_DataTree $object )` Update the data in an object. Does not change the object's parent or name, just serialized data or attributes. Update the data in an object. Does not change the object's parent or name, just serialized data or attributes. Parameters `$object` A Horde_DataTree object. Returns `TODO`
`public integer`	# `_cmp( array $a, array $b )` Sort two objects by their order field, and if that is the same, alphabetically (case insensitive) by name. Sort two objects by their order field, and if that is the same, alphabetically (case insensitive) by name. You never call this function; it's used in uasort() calls. Do NOT use usort(); you'll lose key => value associations. Parameters `$a` The first object `$b` The second object Returns `integer` 1 if $a should be first, -1 if $b should be first, 0 if they are entirely equal. Private
`public integer`	# `_cmpSorted( array $a, array $b )` Sorts two objects by their sorter hash field. Sorts two objects by their sorter hash field. You never call this function; it's used in uasort() calls. Do NOT use usort(); you'll lose key => value associations. Parameters `$a` The first object `$b` The second object Returns `integer` 1 if $a should be first, -1 if $b should be first, 0 if they are entirely equal. Private
`public Horde_DataTree &`	# `factory( mixed $driver, array $params = null )` Attempts to return a concrete Horde_DataTree instance based on $driver. Attempts to return a concrete Horde_DataTree instance based on $driver. Parameters `$driver` <p>The type of concrete Horde_DataTree subclass to return. This is based on the storage driver ($driver). The code is dynamically included. If $driver is an array, then we will look in $driver[0]/lib/DataTree/ for the subclass implementation named $driver[1].php.</p> `$params` <p>A hash containing any additional configuration or connection parameters a subclass might need. Here, we need 'group' = a string that defines top-level groups of objects.</p> Returns `Horde_DataTree` The newly created concrete Horde_DataTree instance, or false on an error.
`public Horde_DataTree &`	# `singleton( mixed $driver, array $params = null )` Attempts to return a reference to a concrete Horde_DataTree instance based on $driver. Attempts to return a reference to a concrete Horde_DataTree instance based on $driver. It will only create a new instance if no Horde_DataTree instance with the same parameters currently exists. This should be used if multiple Horde_DataTree sources (and, thus, multiple Horde_DataTree instances) are required. This method must be invoked as: $var = &Horde_DataTree::singleton(); Parameters `$driver` <p>Type of concrete Horde_DataTree subclass to return, based on storage driver ($driver). The code is dynamically included. If $driver is an array, then look in $driver[0]/lib/DataTree/ for subclass implementation named $driver[1].php.</p> `$params` <p>A hash containing any additional configuration or connection parameters a subclass might need.</p> Returns `Horde_DataTree` The concrete Horde_DataTree reference, or false on an error.

Properties summary
`public array`	`$_data` Array of all data: indexed by id. The format is: array(id => 'name' => name, 'parent' => parent). Array of all data: indexed by id. The format is: array(id => 'name' => name, 'parent' => parent).	# `array()`
`public array`	`$_nameMap` A hash that can be used to map a full object name (parent:child:object) to that object's unique ID. A hash that can be used to map a full object name (parent:child:object) to that object's unique ID.	# `array()`
`public array`	`$_sortHash` Actual attribute sorting hash. Actual attribute sorting hash.	# `null`
`public array`	`$_params` Hash containing connection parameters. Hash containing connection parameters.	# `array()`

Packages

Classes

Class Horde_DataTree

Direct known subclasses

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Note

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Private

Parameters