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

Class: Tree_Memory

Source Location: /Tree-0.3.7/Tree/Memory.php

Class Overview

Tree_Common
   |
   --Tree_Memory

this class can be used to step through a tree using ['parent'],['child']


Author(s):

Version:

  • 2001/06/27

Variables

Methods


Child classes:

treeClass
this class can be used to step through a tree using ['parent'],['child']

Inherited Variables

Inherited Methods

Class: Tree_Common

Tree_Common::getAllChildren()
gets all the children and grand children etc.
Tree_Common::getAllChildrenIds()
gets all the children-ids and grand children-ids
Tree_Common::getChildId()
Tree_Common::getChildrenIds()
get the ids of the children of the given element
Tree_Common::getDepth()
return the maximum depth of the tree
Tree_Common::getFirstRootId()
Tree_Common::getIdByPath()
Tree_Common::getLeftId()
Tree_Common::getLevel()
get the level, which is how far below the root the element with the given id is
Tree_Common::getNextId()
Tree_Common::getOption()
Tree_Common::getOptions()
returns all the options
Tree_Common::getParentId()
get the id of the parent for the given element
Tree_Common::getParents()
this gets all the preceeding nodes, the parent and it's parent and so on
Tree_Common::getParentsIds()
get the ids of the parents and all it's parents and so on it simply returns the ids of the elements returned by getParents()
Tree_Common::getPath()
gets the path to the element given by its id
Tree_Common::getPathAsString()
returns the path as a string
Tree_Common::getPreviousId()
Tree_Common::getRightId()
Tree_Common::getRootId()
Tree_Common::hasChildren()
returns if the given element has any children
Tree_Common::isChildOf()
returns if $childId is a child of $id
Tree_Common::setOption()
Tree_Common::setOptions()
set a number of options which are simply given in an array
Tree_Common::Tree_Options()
this constructor sets the options, since i normally need this and in case the constructor doesnt need to do anymore i already have it done :-)
Tree_Common::_getAllChildren()
this method gets all the children recursively

Class Details

[line 90]
this class can be used to step through a tree using ['parent'],['child']

the tree is saved as flat data in a db, where at least the parent needs to be given if a previous member is given too then the order on a level can be determined too actually this class was used for a navigation tree now it is extended to serve any kind of tree you can unambigiously refer to any element by using the following syntax tree->data[currentId][<where>]...[<where>] <where> can be either "parent", "child", "next" or "previous", this way you can "walk" from any point to any other point in the tree by using <where> in any order you want example (in parentheses the id): root +---level 1_1 (1) | +----level 2_1 (2) | +----level 2_2 (3) | +-----level 3_1 (4) +---level 1_2 (5)

the database table to this structure (without defined order) id parentId name

  1. 0 level 1_1
  2. 1 level 2_1
  3. 1 level 2_1
  4. 3 level 3_1
  5. 0 level 1_2
now you can refer to elements for example like this (all examples assume you know the structure): go from "level 3_1" to "level 1_1": $tree->data[4]['parent']['parent'] go from "level 3_1" to "level 1_2": $tree->data[4]['parent']['parent']['next'] go from "level 2_1" to "level 3_1": $tree->data[2]['next']['child'] go from "level 2_2" to "level 2_1": $tree->data[3]['previous'] go from "level 1_2" to "level 3_1": $tree->data[5]['previous']['child']['next']['child']

on a pentium 1.9 GHz 512 MB RAM, Linux 2.4, Apache 1.3.19, PHP 4.0.6 performance statistics for version 1.26, using examples/Tree/Tree.php

  • reading from DB and preparing took: 0.14958894252777
  • building took: 0.074488043785095
  • buildStructure took: 0.05151903629303
  • setting up the tree time: 0.29579293727875
  • number of elements: 1564
  • deepest level: 17
so you can use it for tiny-big trees too :-) but watch the db traffic, which might be considerable, depending on your setup.

FIXXXME there is one really bad thing about the entire class, at some points there are references to $this->data returned, or the programmer can even access this->data, which means he can change the structure, since this->data can not be set to read-only, therefore this->data has to be handled with great care!!! never do something like this:

  1.  $x &$tree->data[<some-id>]$x $y;
this overwrites the element in the structure !!!



[ Top ]


Class Variables

$children = array()

[line 121]

it contains all the parents and their children, where the parentId is the key and all the children are the values, this is for speeding up the tree-building process

Type:   array


[ Top ]

$data = array()

[line 99]

this array contains the pure data from the DB which are always kept, since all other structures will only make references on any element and those data are extended by the elements 'parent' 'children' etc...

Type:   array


[ Top ]

$debug =  0

[line 137]

  • Var: the debug mode, if > 0 then debug info are shown, actually those messages only show performance times
  • Access: public

Type:   integer


[ Top ]



Method Detail

Tree_Memory (Constructor)   [line 175]

Tree_Memory Tree_Memory( mixed $type, [array $dsn = ''], [ $options = array()])

set up this object

Parameters:

mixed   $type     this is a DSN for the PEAR::DB, can be either an object/string
array   $dsn     additional options you can set
   $options     

[ Top ]

add   [line 437]

mixed add( array $newValues, [int $parentId = 0], [int $prevId = 0])

adds _one_ new element in the tree under the given parent

the values' keys given have to match the db-columns, because the value gets inserted in the db directly to add an entire node containing children and so on see 'addNode()'


Parameters:

array   $newValues     this array contains the values that shall be inserted in the db-table
int   $parentId     the parent id
int   $prevId     the prevId

[ Top ]

addNode   [line 853]

mixed addNode( array $node)

Adds multiple elements. You have to pass those elements in a multidimensional array which represents the tree structure as it shall be added (this array can of course also simply contain one element).

The following array $x passed as the parameter $x[0] = array('name' => 'bla', 'parentId' => '30', array('name' => 'bla1', 'comment' => 'foo', array('name' => 'bla2'), array('name' => 'bla2_1') ), array('name'=>'bla1_1'), ); $x[1] = array('name' => 'fooBla', 'parentId' => '30');

would add the following tree (or subtree/node) under the parent with the id 30 (since 'parentId'=30 in $x[0] and in $x[1]): +--bla | +--bla1 | | +--bla2 | | +--bla2_1 | +--bla1_1 +--fooBla


Parameters:

array   $node     the tree to be inserted, represents the tree structure, see add() for the exact member of each node

[ Top ]

buildStructure   [line 680]

boolean buildStructure( integer $parentId, integer &$insertIn)

builds the structure in the parameter $insertIn this function works recursively down into depth of the folder structure it builds an array which goes as deep as the structure goes
  • Return: returns always true
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/05/02
  • Access: public

Parameters:

integer   $parentId     the parent for which it's structure shall be built
integer   &$insertIn     the array where to build the structure in given as a reference to be sure the substructure is built in the same array as passed to the function

[ Top ]

copy   [line 1497]

boolean copy( the $srcId, the $destId)

NOT IMPLEMENTED YET copies a part of the tree under a given parent
  • Return: true on success
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/12/19
  • Access: public

Parameters:

the   $srcId     id of the element which is copied, all its children are copied too
the   $destId     id that shall be the new parent

[ Top ]

getChild   [line 1117]

void &getChild( mixed $id)

returns the child if the node given has one !!! ATTENTION watch out that you never change any of the data returned, since they are references to the internal property $data

Parameters:

mixed   $id     the id of the node to get the child for

[ Top ]

getChildren   [line 1389]

boolean getChildren( $ids, [integer $levels = 1], integer $id)

returns the children of the given ids
  • Return: true if the node has children
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/12/17
  • Access: public

Parameters:

integer   $id     the id of the node to check for children
integer   $levels     the children of how many levels shall be returned
   $ids     

[ Top ]

getElementByPath   [line 1075]

integer &getElementByPath( string $path, [integer $startId = 0], [string $nodeName = 'name'], [string $seperator = '/'])

gets an element given by it's path as a reference
  • Return: the id of the searched element
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/01/21
  • Access: public

Parameters:

string   $path     the path to search for
integer   $startId     the id where to search for the path
string   $nodeName     the name of the key that contains the node name
string   $seperator     the path separator

[ Top ]

getFirstRoot   [line 1280]

returns &getFirstRoot( )

this gets the first element that is in the root node

i think that there can't be a "getRoot" method since there might be multiple number of elements in the root node, at least the way it works now

  • Return: the first root element
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/12/10
  • Access: public

[ Top ]

getIdByPath   [line 1225]

integer getIdByPath( string $path, [integer $startId = 0], [string $nodeName = 'name'], [string $seperator = '/'])

return the id of the element which is referenced by $path

this is useful for xml-structures, like: getIdByPath('/root/sub1/sub2') this requires the structure to use each name uniquely if this is not given it will return the first proper path found i.e. there should only be one path /x/y/z

  • Return: the id of the searched element
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/11/28
  • Access: public

Overrides Tree_Common::getIdByPath() (parent method not documented)

Parameters:

string   $path     the path to search for
integer   $startId     the id where to search for the path
string   $nodeName     the name of the key that contains the node name
string   $seperator     the path seperator

[ Top ]

getLevel   [line 1098]

void getLevel( mixed $id)

get the level, which is how far below the root are we?

Overrides Tree_Common::getLevel() (get the level, which is how far below the root the element with the given id is)

Parameters:

mixed   $id     the id of the node to get the level for

[ Top ]

getNext   [line 1157]

mixed &getNext( mixed $id)

returns the next element if the node given has one !!! ATTENTION watch out that you never change any of the data returned, since they are references to the internal property $data
  • Return: reference to the next element or false if there is none
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/01/17
  • Access: public

Parameters:

mixed   $id     the id of the node to get the child for

[ Top ]

getNode   [line 1326]

array &getNode( [integer $startId = 0], [integer $depth = 0])

gets the tree under the given element in one array, sorted so you can go through the elements from begin to end and list them as they are in the tree, where every child (until the deepest) is retreived
  • Return: sorted as listed in the tree
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/12/17
  • See: &_getNode()
  • Access: public

Parameters:

integer   $startId     the id where to start walking
integer   $depth     this number says how deep into the structure the elements shall be retreived

[ Top ]

getParent   [line 1137]

void &getParent( mixed $id)

returns the child if the node given has one !!! ATTENTION watch out that you never change any of the data returned, since they are references to the internal property $data

Parameters:

mixed   $id     the id of the node to get the child for

[ Top ]

getPath   [line 907]

array getPath( mixed $id)

gets the path to the element given by its id !!! ATTENTION watch out that you never change any of the data returned, since they are references to the internal property $data
  • Return: this array contains all elements from the root to the element given by the id
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/10/10
  • Access: public

Overrides Tree_Common::getPath() (gets the path to the element given by its id)

Parameters:

mixed   $id     the id of the node to get the path for

[ Top ]

getPrevious   [line 1177]

mixed &getPrevious( mixed $id)

returns the previous element if the node given has one !!! ATTENTION watch out that you never change any of the data returned, since they are references to the internal property $data
  • Return: reference to the next element or false if there is none
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/02/05
  • Access: public

Parameters:

mixed   $id     the id of the node to get the child for

[ Top ]

getRoot   [line 1302]

returns &getRoot( )

since in a nested tree there can only be one root

which i think (now) is correct, we also need an alias for this method this also makes all the methods in Tree_Common, which access the root element work properly!

  • Return: the first root element
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/07/26
  • Access: public

[ Top ]

isNode   [line 1419]

boolean isNode( [integer $id = 0])

returns if the given element is a valid node
  • Return: true if the node has children
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/12/21
  • Access: public

Parameters:

integer   $id     the id of the node to check for children

[ Top ]

move   [line 545]

boolean move( integer $idsToMove, integer $newParentId, [integer $newPrevId = 0])

move an entry under a given parent or behind a given entry.

!!! the 'move behind another element' is only implemented for nested trees now!!!. If a newPrevId is given the newParentId is dismissed! call it either like this: $tree->move(x, y) to move the element (or entire tree) with the id x under the element with the id y or

  1.       // ommit the second parameter by setting it to 0
  2.       $tree->move(x0y);
to move the element (or entire tree) with the id x behind the element with the id y or
  1.       $tree->move(array(x1,x2,x3)...
the first parameter can also be an array of elements that shall be moved the second and third para can be as described above

  • Return: true for success
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/06/08
  • Access: public

Parameters:

integer   $idsToMove     the id(s) of the element(s) that shall be moved
integer   $newParentId     the id of the element which will be the new parent
integer   $newPrevId     if prevId is given the element with the id idToMove shall be moved _behind_ the element with id=prevId if it is 0 it will be put at the beginning

[ Top ]

remove   [line 461]

boolean remove( mixed $id)

removes the given node and all children if removeRecursively is on
  • Return: true on success
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/01/24
  • Access: public

Parameters:

mixed   $id     the id of the node to be removed

[ Top ]

setRemoveRecursively   [line 940]

void setRemoveRecursively( [boolean $case = true])

sets the remove-recursively mode, either true or false

Parameters:

boolean   $case     set to true if removing a tree level shall remove all it's children and theit children

[ Top ]

setup   [line 256]

true setup( [array $data = null])

  • Return: or Tree_Error
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/01/19
  • Access: public

Parameters:

array   $data     the result of a query which retreives (all) the tree data from a source

[ Top ]

setupByRawData   [line 235]

boolean setupByRawData( $string)

  • Return: true if the setup succeeded
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/01/19
  • Access: public

Parameters:

   $string     

[ Top ]

switchDataSource   [line 211]

boolean switchDataSource( string $type, [array $dsn = ''], [ $options = array()])

use this to switch data sources on the run

i.e. if you are reading the data from a db-tree and want to save it as xml data (which will work one day too) or reading the data from an xml file and writing it in the db which should already work

  • Return: true on success
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/01/17
  • Access: public

Parameters:

string   $type     this is a DSN of the for that PEAR::DB uses it only that additionally you can add parameters like ...?table=test_table to define the table.
array   $dsn     additional options you can set
   $options     

[ Top ]

update   [line 644]

mixed update( integer $id, array $data)

update data in a node
  • Return: either boolean or an error object if the method is not implemented
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2002/01/29
  • Access: public

Parameters:

integer   $id     the ID of the element that shall be updated
array   $data     the data to update

[ Top ]

varDump   [line 1442]

void varDump( [ $node = 0])

this is for debugging, dumps the entire data-array an extra method is needed, since this array contains recursive elements which make a normal print_f or var_dump not show all the data

Parameters:

   $node     

[ Top ]

walk   [line 736]

mixed walk( mixed $walkFunction, [array $id = 0], [string $returnType = 'string'])

this method only serves to call the _walk method and reset $this->walkReturn that will be returned by all the walk-steps
  • Return: this is all the return data collected from all the walk-steps
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/11/25
  • Access: public

Parameters:

mixed   $walkFunction     the name of the function to call for each walk step, or an array for a method, where [0] is the method name and [1] the object
array   $id     the id to start walking through the tree, everything below is walked through
string   $returnType     the return of all the walk data will be of the given type (values: string, array)

[ Top ]

_move   [line 580]

mixed _move( integer $idToMove, integer $newParentId, [integer $prevId = 0])

this method moves one tree element

Parameters:

integer   $idToMove     the id of the element that shall be moved
integer   $newParentId     the id of the element which will be the new parent
integer   $prevId     if prevId is given the element with the id idToMove shall be moved _behind_ the element with id=prevId if it is 0 it will be put at the beginning

[ Top ]

_remove   [line 502]

boolean _remove( $element, mixed $id)

collects the ID's of the elements to be removed
  • Return: true on success
  • Author: Wolfram Kriesing <wolfram@kriesing.de>
  • Version: 2001/10/09
  • Access: public

Parameters:

mixed   $id     the id of the node to be removed
   $element     

[ Top ]


Documentation generated on Wed, 04 Jan 2012 03:00:25 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.