DB_NestedSet
[ class tree: DB_NestedSet ] [ index: DB_NestedSet ] [ all elements ]

Class: DB_NestedSet

Source Location: /DB_NestedSet-1.4.1/NestedSet.php

Class Overview


DB_NestedSet is a class for handling nested sets


Author(s):

Version:

  • $Revision: 244559 $

Variables

Methods


Child classes:

DB_NestedSet_DB
Wrapper class for PEAR::DB
DB_NestedSet_MDB2
Wrapper class for PEAR::MDB2
DB_NestedSet_MDB
Wrapper class for PEAR::MDB

Inherited Variables

Inherited Methods


Class Details

[line 61]
DB_NestedSet is a class for handling nested sets
  • Author: Daniel Khan <dk@webcluster.at>
  • Version: $Revision: 244559 $
  • Access: public


[ Top ]


Class Variables

$cache =  false

[line 158]

  • Var: Optional PEAR::Cache object
  • Access: public

Type:   object cache


[ Top ]

$debug =  0

[line 137]

  • Var: Enable debugging statements?
  • Access: public

Type:   bool


[ Top ]

$lockTTL =  1

[line 130]

  • Var: The time to live of the lock
  • Access: public

Type:   int


[ Top ]

$lock_table =  'tb_locks'

[line 91]

  • Var: The table to handle locking
  • Access: public

Type:   string


[ Top ]

$messages = array(
    NESE_ERROR_RECURSION => '%s: This operation would lead to a recursion',
    NESE_ERROR_TBLOCKED => 'The structure Table is locked for another database operation, please retry.',
    NESE_ERROR_NODRIVER => 'The selected database driver %s wasn\'t found',
    NESE_ERROR_NOTSUPPORTED => 'Method not supported yet',
    NESE_ERROR_NOHANDLER => 'Event handler not found',
    NESE_ERROR_PARAM_MISSING => 'Parameter missing',
    NESE_MESSAGE_UNKNOWN => 'Unknown error or message',
    NESE_ERROR_NOT_FOUND => '%s: Node %s not found',
    NESE_ERROR_WRONG_MPARAM => '%s: %s'
    )

[line 271]

  • Var: Map of error messages to their descriptions

Type:   array


[ Top ]

$node_table =  'tb_nodes'

[line 84]

  • Var: The table with the actual tree data
  • Access: public

Type:   string


[ Top ]

$params = array('STRID' => 'id',
    'ROOTID' => 'rootid',
    'l' => 'l',
    'r' => 'r',
    'STREH' => 'norder',
    'LEVEL' => 'level',
    // 'parent'=>'parent', // Optional but very useful
    'STRNA' => 'name'
    )

[line 68]

  • Var: The field parameters of the table with the nested set. Format: 'realFieldName' => 'fieldId'
  • Access: public

Type:   array


[ Top ]

$secondarySort =

[line 107]

Secondary order field. Normally this is the order field, but can be changed to something else (i.e. the name field so that the tree can be shown alphabetically)
  • Access: public

Type:   string


[ Top ]

$sequence_table =

[line 98]

  • Var: The table used for sequences
  • Access: public

Type:   string


[ Top ]



Method Detail

addListener   [line 2075]

string addListener( string $event, &$listener, string $listener)

Add an event listener

Adds an event listener and returns an ID for it

Known events are
 nodeCreate
 nodeDelete
 nodeUpdate
 nodeCopy
 nodeLoad

  • Access: public

Parameters:

string   $event     The event name
string   $listener     The listener object
   &$listener     

[ Top ]

apiVersion   [line 2129]

void apiVersion( )


[ Top ]

convertTreeModel   [line 2463]

bool convertTreeModel( &$orig, &$copy, [integer $_parent = false], object $)

Convert a <1.3 tree into a 1.3 tree format

This will convert the tree into a format needed for some new features in 1.3. Your <1.3 tree will still work without converting but some new features like preorder sorting won't work as expected.

 Usage:
 - Create a new node table (tb_nodes2) from the current node table (tb_nodes1) (only copy the structure).
 - Create a nested set instance of the 'old' set (NeSe1) and one of the new set (NeSe2)
 - Now you have 2 identical objects where only node_table differs
 - Call DB_NestedSet::convertTreeModel(&$orig, &$copy);
 - After that you have a cleaned up copy of tb_nodes1 inside tb_nodes2

  • Return: True uns success
  • Access: public

Parameters:

object   $     DB_NestedSet $copy Object where the new tree is copied to
integer   $_parent     ID of the parent node (private)
   &$orig     
   &$copy     

[ Top ]

createLeftNode   [line 1205]

mixed createLeftNode( int $id, array $values, bool $returnID)

Creates a node before a given node

 +-- root1
 |
 +-\ root2
 | |
 | |-- subnode2 [new]
 | |-- subnode1 [target]
 | |-- subnode3
 |
 +-- root3

  • Return: The node id or false on error
  • Access: public

Parameters:

int   $id     Target node ID
array   $values     Hash with param => value pairs of the node (see $this->params)
bool   $returnID     Tell the method to return a node id instead of an object. ATTENTION: That the method defaults to return an object instead of the node id has been overseen and is basically a bug. We have to keep this to maintain BC. You will have to set $returnID to true to make it behave like the other creation methods. This flaw will get fixed with the next major version.

[ Top ]

createRightNode   [line 1313]

mixed createRightNode( int $id, array $values, bool $returnID)

Creates a node after a given node

 +-- root1
 |
 +-\ root2
 | |
 | |-- subnode1 [target]
 | |-- subnode2 [new]
 | |-- subnode3
 |
 +-- root3

  • Return: The node id or false on error
  • Access: public

Parameters:

int   $id     Target node ID
array   $values     Hash with param => value pairs of the node (see $this->params)
bool   $returnID     Tell the method to return a node id instead of an object. ATTENTION: That the method defaults to return an object instead of the node id has been overseen and is basically a bug. We have to keep this to maintain BC. You will have to set $returnID to true to make it behave like the other creation methods. This flaw will get fixed with the next major version.

[ Top ]

createRootNode   [line 984]

mixed createRootNode( array $values, [integer $id = false], [bool $first = false], [string $pos = NESE_MOVE_AFTER])

Creates a new root node. If no id is specified then it is either added to the beginning/end of the tree based on the $pos.

Optionally it deletes the whole tree and creates one initial rootnode

 +-- root1 [target]
 |
 +-- root2 [new]
 |
 +-- root3

  • Return: The node id or false on error
  • Access: public

Parameters:

array   $values     Hash with param => value pairs of the node (see $this->params)
integer   $id     ID of target node (the rootnode after which the node should be inserted)
bool   $first     Danger: Deletes and (re)init's the hole tree - sequences are reset
string   $pos     The position in which to insert the new node.

[ Top ]

createSubNode   [line 1100]

mixed createSubNode( integer $id, array $values)

Creates a subnode

 +-- root1
 |
 +-\ root2 [target]
 | |
 | |-- subnode1 [new]
 |
 +-- root3

  • Return: The node id or false on error
  • Access: public

Parameters:

integer   $id     Parent node ID
array   $values     Hash with param => value pairs of the node (see $this->params)

[ Top ]

deleteNode   [line 1405]

bool deleteNode( int $id)

Deletes a node
  • Return: True if the delete succeeds
  • Access: public

Parameters:

int   $id     ID of the node to be deleted

[ Top ]

factory   [line 344]

object The &factory( string $driver, string $dsn, [array $params = array()])

Handles the returning of a concrete instance of DB_NestedSet based on the driver.

If the class given by $driver allready exists it will be used. If not the driver will be searched inside the default path ./NestedSet/

  • Return: DB_NestedSet object
  • Access: public

Parameters:

string   $driver     The driver, such as DB or MDB
string   $dsn     The dsn for connecting to the database
array   $params     The field name params for the node table

[ Top ]

getAllNodes   [line 383]

mixed getAllNodes( [bool $keepAsArray = false], [bool $aliasFields = true], [array $addSQL = array()])

Fetch the whole NestedSet
  • Return: False on error, or an array of nodes
  • Access: public

Parameters:

bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

getBranch   [line 485]

mixed getBranch( int $id, [bool $keepAsArray = false], [bool $aliasFields = true], [array $addSQL = array()])

Fetch the whole branch where a given node id is in
  • Return: False on error, or an array of nodes
  • See: _addSQL
  • Access: public

Parameters:

int   $id     The node ID
bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

getChildren   [line 703]

mixed getChildren( int $id, [bool $keepAsArray = false], [bool $aliasFields = true], [bool $forceNorder = false], [array $addSQL = array()])

Fetch the children _one level_ after of a node given by id
  • Return: False on error, or an array of nodes
  • See: _addSQL
  • Access: public

Parameters:

int   $id     The node ID
bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
bool   $forceNorder     (optional) Force the result to be ordered by the norder param (as opposed to the value of secondary sort). Used by the move and add methods.
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

getParent   [line 621]

mixed getParent( int $id, [bool $keepAsArray = false], [bool $aliasFields = true], [array $addSQL = array()], [ $useDB = true])

Fetch the immediate parent of a node given by id
  • Return: False on error, or the parent node
  • See: _addSQL
  • Access: public

Parameters:

int   $id     The node ID
bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
array   $addSQL     (optional) Array of additional params to pass to the query.
   $useDB     

[ Top ]

getParents   [line 559]

mixed getParents( int $id, [bool $keepAsArray = false], [bool $aliasFields = true], [array $addSQL = array()])

Fetch the parents of a node given by id
  • Return: False on error, or an array of nodes
  • See: _addSQL
  • Access: public

Parameters:

int   $id     The node ID
bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

getRootNodes   [line 438]

mixed getRootNodes( [bool $keepAsArray = false], [bool $aliasFields = true], [array $addSQL = array()])

Fetches the first level (the rootnodes) of the NestedSet
  • Return: False on error, or an array of nodes
  • See: _addSQL
  • Access: public

Parameters:

bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

getSiblings   [line 668]

mixed getSiblings( int $id, [bool $keepAsArray = false], [bool $aliasFields = true], [array $addSQL = array()])

Fetch all siblings of the node given by id Important: The node given by ID will also be returned Do a unset($array[$id]) on the result if you don't want that
  • Return: False on error, or the parent node
  • See: _addSQL
  • Access: public

Parameters:

int   $id     The node ID
bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

getSubBranch   [line 759]

mixed getSubBranch( string $id, [bool $keepAsArray = false], [bool $aliasFields = true], [array $addSQL = array()])

Fetch all the children of a node given by id

getChildren only queries the immediate children getSubBranch returns all nodes below the given node

  • Return: False on error, or an array of nodes
  • See: _addSQL
  • Access: public

Parameters:

string   $id     The node ID
bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

isParent   [line 900]

bool isParent( mixed $parent, mixed $child)

See if a given node is a parent of another given node

A node is considered to be a parent if it resides above the child So it doesn't mean that the node has to be an immediate parent. To get this information simply compare the levels of the two nodes after you know that you have a parent relation.

  • Return: True if it's a parent
  • Access: public

Parameters:

mixed   $parent     The parent node as array or object
mixed   $child     The child node as array or object

[ Top ]

moveTree   [line 1541]

int moveTree( int $id, $targetid, constant $pos, [bool $copy = false], int $target)

Wrapper for node moving and copying
  • Return: ID of the moved node or false on error
  • See: _moveRoot2Root
  • See: _moveAcross
  • See: _moveInsideLevel
  • Access: public

Parameters:

int   $id     Source ID
int   $target     Target ID
constant   $pos     Position (use one of the NESE_MOVE_* constants)
bool   $copy     Shall we create a copy
   $targetid     

[ Top ]

pickNode   [line 839]

mixed pickNode( int $id, [bool $keepAsArray = false], [bool $aliasFields = true], [string $idfield = 'id'], [array $addSQL = array()])

Fetch the data of a node with the given id
  • Return: False on error, or an array of nodes
  • See: _addSQL
  • Access: public

Parameters:

int   $id     The node id of the node to fetch
bool   $keepAsArray     (optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?
bool   $aliasFields     (optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?
string   $idfield     (optional) Which field has to be compared with $id? This is can be used to pick a node by other values (e.g. it's name).
array   $addSQL     (optional) Array of additional params to pass to the query.

[ Top ]

removeListener   [line 2093]

bool removeListener( string $event, string $listenerID)

Removes an event listener

Removes the event listener with the given ID

  • Access: public

Parameters:

string   $event     The ivent name
string   $listenerID     The listener's ID

[ Top ]

setAttr   [line 2146]

bool setAttr( array $attr)

Sets an object attribute
  • Access: public

Parameters:

array   $attr     An associative array with attributes

[ Top ]

setDbOption   [line 2200]

void setDbOption( $option, $val)

Sets a db option. Example, setting the sequence table format
  • Var: The option to set
  • Access: public

Parameters:

   $option     
   $val     

[ Top ]

setsortMode   [line 2182]

Current setsortMode( [constant $sortMode = false])

This enables you to set specific options for each output method
  • Return: sortMode
  • Access: public

Parameters:

constant   $sortMode     

[ Top ]

testLock   [line 2210]

void testLock( )

Tests if a database lock is set
  • Access: public

[ Top ]

triggerEvent   [line 2112]

bool triggerEvent( string $event, &$node, [array $eparams = false], object $)

Triggers and event an calls the event listeners
  • Access: public

Parameters:

string   $event     The Event that occured
object   $     node $node A Reference to the node object which was subject to changes
array   $eparams     A associative array of params which may be needed by the handler
   &$node     

[ Top ]

updateNode   [line 1487]

bool updateNode( int $id, array $values, [ $_internal = false], bool $_intermal)

Changes the payload of a node
  • Return: True if the update is successful
  • Access: public

Parameters:

int   $id     Node ID
array   $values     Hash with param => value pairs of the node (see $this->params)
bool   $_intermal     Internal use only. Used to skip value validation. Leave this as it is.
   $_internal     

[ Top ]


Documentation generated on Sun, 25 Apr 2010 21:30:09 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.