Baobab API¶

Copyright and License¶

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Exceptions¶

class sp_Error¶: Root exception. Each exception thrown in a Sideralis Programs library derive from this class

class sp_MySQL_Error¶

Exception holding informations about errors occurred when using mysql

Parameters:	$conn_or_msg (mysqli or string) – database connection object or an exception message $err_code (int) – mysql error code

class BaobabNode($id, $lft, $rgt, $parentId[, $fields=NULL])¶

Node of a Baobab tree

Parameters:	$id (int) – the node id $lft (int) – the node left bound $rgt (int) – the node right bound $parentId (int or NULL) – the parent’s node id, if any $fields_values (array or NULL) – additional fields of the node (mapping fieldName => value)

Attributes:

id int, node id

lft int, left value

rgt int, right value

parentNode int, the parent node id

fields_values array, additional fields of the node

children array, instances of BaobabNode children of the current node

Note

this class doesn’t have database interaction, its purpose is just to have a runtime representation of a Baobab tree. The data inserted is supposed to be valid in his tree (e.g. $this->lft cant’ be -1 or major of any node right value)

appendChild($child)¶

Add a node as last sibling of the node’s children.

Parameters:	$child (`BaobabNode`) – append a node to the list of this node children

stringify([$fields=NULL[, $diveInto=TRUE[, $indentChar=" "[, $indentLevel=0]]]])¶

Return a representation of the tree as a string.

Parameters:	$fields (array) – what node fields include in the output. id, lft and rgt are always included. $diveInto (boolean) – wheter to continue with node’s children or not $indentChar (string) – character to use to indent $indentLevel (int) – how deep we are indenting
Returns:	tree or node representation
Return type:	string

Note

$indentLevel is meant for internal use only.

isRightmost()¶

Check if the node is rightmost between his siblings.

Returns:	whether if the node is the rightmost or not
Return type:	boolean

isLeftmost()¶

Check if the node is leftmost between his siblings.

Returns:	whether if the node is the leftmost or not
Return type:	boolean

Baobab¶

class Baobab($db, $forest_name[, $tree_id=NULL])¶

This class lets you create, populate search and destroy a tree stored using the Nested Set Model described by Joe Celko.

Parameters:

$db (an instance of mysqli_connect) – mysqli database connection in object oriented style
$forest_name (string) – name of the forest, will be used to create an homonymous table that will hold the data.
$tree_id (int or NULL) – id of the tree (to create a new tree it must be NULL or an unused tree_id number). If there is only a tree in the table, you can load it with -1; A new tree created using NULL has $tree_id = 0 until an appendChild occurs.

Attributes:: tree_id int, id of the tree (0 means it’s new with no nodes added yet)

build()¶

Apply the database schema

Returns:	TRUE if any table was added, FALSE if the build was skipped (e.g. if the tree yet exists calling build will do nothing and return FALSE).
Return type:	boolean

Note

This is automatically called while instantiating the class. If the version of the library didn’t change in the meantime, nothing happens, otherwise it will throw an exception to inform you to use Baobab:upgrade()

static upgrade($db[, $untilVersion=NULL])¶

Upgrade the database schema of all the trees to reflect the current library’s version.

Parameters:	$db (mysqli) – mysqli database connection object $untilVersion (string or NULL) – version at which stop (or NULL to update to last version)

Warning

To avoid any possible data loss you should backup your database’s tables first.

Warning

For each release read release notes and check what’s going to happen when you upgrade your database (see sql/upgrade/* files). Eventually stop with $untilVersion at a certain point to apply needed tweaks.

destroy()¶

Remove every table, procedure or view that were created via: Baobab.build for the current tree name

Parameters:	$removeDataTable (boolean) – unless this value is TRUE, avoid to delete the table that holds the tree data

clean()¶: Delete all the records about this tree. Other trees in the same table will be unaffected.

static cleanAll($db, $forest_name)¶

Delete all the records in $forest_name

Parameters:	$db (an instance of mysqli_connect) – mysqli database connection in object oriented style $forest_name (string) – name of the forest, equals to the name of the table holding the data

getRoot()¶

Return the id of the first node of the tree.

Returns:	id of the root, or NULL if empty
Return type:	int or NULL

getParent($id_node)¶

Return the id of the node’s parent.

Returns:	id of the parent, or NULL if node is root
Return type:	int or NULL

getSize([$id_node=NULL])¶

Retrieve the number of nodes of the subtree starting at $id_node (or at tree root if $id_node is NULL).

Parameters:	$id_node (int or NULL) – id of the node to count from (or NULL to count from root)
Returns:	the number of nodes in the selected subtree
Return type:	int

getDescendants([$id_node=NULL])¶

Retrieve all the descendants of a node

Parameters:	$id_node (int or NULL) – id of the node whose descendants we’re searching for, or NULL to start from the tree root.
Returns:	the ids of node’s descendants, in ascending order
Return type:	array

getLeaves([$id_node=NULL])¶

Find the leaves of a subtree.

Parameters:	$id_node (int or NULL) – id of a node or NULL to start from the tree root
Returns:	the ids of the leaves, ordered from left to right
Return type:	array

getLevels()¶

Find at what level of the tree each node is.

Parameters:	$id_node (int or NULL) – id of a node or NULL to start from the tree root
Returns:	associative arrays with id => number, level => number, unordered
Return type:	array

Note

tree root is at level 0

getPath($id_node[, $fields=NULL[, $squash=FALSE]])¶

Find all the nodes between tree root and a node.

Parameters:	$id_node (int) – id of the node used to calculate the path to $fields (mixed) – if not NULL, a string with a Baobab tree field name or an array of field names $squash (boolean) – if TRUE the method will return an array with just the values of the first field in $fields (if $fields is empty it will default to “id” )
Returns:	sequence of associative arrays mapping for each node fieldName => value, where field names are the one present in $fields plus the field “id” (unless $squash was set), ordered from root to $id_node
Return type:	array

Example (considering a tree with two nodes with a field ‘name’):

php> $tree->getPath(2, array("name"))
array([0] => array([id] => 1, [name] => 'rootName'), array([id] => 2, [name] => 'secondNodeName']))
php> join("/", $tree->getPath(2, "name", TRUE))
"rootName/secondNodeName"

getFirstNChildren($id_parent[, $howMany=NULL[, $fromLeftToRight=TRUE]])¶

Find the first n node’s children starting from left or right.

Parameters:	$id_parent (int) – id of the parent node $howMany (int or NULL) – maximum number of children to retrieve (NULL means all) $fromLeftToRight (boolean) – what order the children must follow
Returns:	ids of the children nodes, ordered from left to right
Return type:	array

getChildren($id_parent)¶

Find all node’s children

Parameters:	$id_parent (int) – id of the parent node
Returns:	ids of the children nodes, ordered from left to right
Return type:	array

getFirstChild($id_parent)¶

Find the leftmost child of a node

Parameters:	$id_parent (int) – id of the parent node
Returns:	id of the leftmost child node, or 0 if not found
Return type:	int

getLastChild($id_parent)¶

Find the rightmost child of a node

Parameters:	$id_parent (int) – id of the parent node
Returns:	id of the rightmost child node, or 0 if not found
Return type:	int

getChildAtIndex($id_parent, $index)¶

Find the nth child of a parent node

Parameters:	$id_parent (int) – id of the parent node $index (int) – position between his siblings (0 is first). Negative indexes are allowed (-1 is the last sibling).
Returns:	id of the nth child node
Return type:	int

getTree([$className="BaobabNode"[, $appendChild="appendChild"]])¶

Create a tree from the database data. It’s possible to use a default tree or use custom classes/functions (it must extends the class BaobabNode)

Parameters:	$className (string) – name of the class holding a node’s information $appendChild (string) – method of $className to call to append a node
Returns:	a node instance
Return type:	instance of $className

deleteNode($id_node[, $close_gaps=True])¶

Delete a node and all of his children. If $close_gaps is TRUE, mantains the Modified Preorder Tree consistent closing gaps.

Parameters:	$id_node (int) – id of the node to drop $close_gaps (boolean) – whether to close the gaps in the tree or not (default TRUE)

Warning

If the gaps are not closed, you can’t use most of the API. Usually you want to avoid closing gaps when you’re deleting different subtrees and want to update the numbering just once (see Baobab.closeGaps)

closeGaps()¶: Update right and left values of each node to ensure there are no gaps in the tree.

Warning

This is a really slow function, use it only if needed (e.g. to delete multiple subtrees and close gaps just once)

getTreeHeight()¶

Calculate the height of the tree

Returns:	the height of the tree
Return type:	int

Note

A tree with one node has height 1.

updateNode($id_node, $fields_values)¶

Update data associeted to a node

Parameters:	$id_node (int) – id of the node to update $fields_values (array) – mapping fields => values to update (only supported types are string, int, float, boolean)

getNodeData($id_node[, $fields=NULL])¶

Retrieve informations about a node.

Parameters:	$id_node (int) – id of the node $fields (array) – fields’ names to read values from
Returns:	the informations found
Return type:	array

appendChild([$id_parent=NULL[, $fields_values=NULL]])¶

Create and append a node as last child of a parent node. If no parent is given, the new node will become the root node.

Parameters:	$id_parent (int or NULL) – id of the parent node $fields_values (array or NULL) – mapping fields => values to assign to the new node
Returns:	id of new node
Return type:	int

insertAfter($id_sibling[, $fields_values=NULL])¶

Create a new node and insert it as the next sibling of the node chosen (which can not be root)

Parameters:	$id_sibling (int) – id of a node in the tree (can not be root) $fields_values (array or NULL) – mapping fields => values to assign to the new node
Returns:	id of the new node
Return type:	int

insertBefore($id_sibling[, $fields_values=NULL])¶

Create a new node and insert it as the previous sibling of the node chosen (which can not be root)

Parameters:	$id_sibling (int) – id of a node in the tree (can not be root) $fields_values (array or NULL) – mapping fields => values to assign to the new node
Returns:	id of the new node
Return type:	int

insertChildAtIndex($id_parent, $index[, $fields_values=NULL])¶

Create a new node and insert it as the nth child of the parent node chosen

Parameters:	$id_parent (int) – id of a node in the tree $index (int) – new child position between his siblings (0 is first). You cannot insert a child as last sibling. Negative indexes are allowed (-1 is the position before the last sibling). $fields_values (array or NULL) – mapping fields => values to assign to the new node
Returns:	id of the new node
Return type:	int

moveAfter($id_to_move, $reference_node)¶

Move a node and all of his children as right sibling of another node.

Parameters:	$id_to_move (int) – id of a node in the tree $reference_node (int) – the node that will become the left sibling of $id_to_move

moveBefore($id_to_move, $reference_node)¶

Move a node and all of his children as left sibling of another node.

Parameters:	$id_to_move (int) – id of a node in the tree $reference_node (int) – the node that will become the left sibling of $id_to_move

moveNodeAtIndex($id_to_move, $id_parent, $index)¶

Move a node as nth child of another node.

Parameters:	$id_to_move (int) – id of a node in the tree $id_parent (int) – id of a node that will become $id_to_move’s parent $index (int) – new child position between his siblings (0 is first). Negative indexes are allowed (-1 is the position before the last sibling).

static import($db, $forest_name, $data)¶

Load data about a single tree (as generated by the export method).

Parameters:	$db (an instance of mysqli_connect) – mysqli database connection in object oriented style $forest_name (string) – name of the forest, equals to the name of the table holding the data $data (string (JSON) or array) – data to import
Returns:	an array of Baobab tree instances
Return type:	array

$data JSON format is like the following

[
 {
   "tree_id": 6, //optional, it could also be one of the fields, or none at all
   "fields" : ["id", "lft", "rgt"],
   "values" :
       [1,1,4,[
           [2,2,3,[]]
       ]]
 }
 // more could follow ...
]

Note

If “id” field is used and the nodes values are not NULL, mustn’t exist in the table a record with that same value.

Note

If “tree_id” is used (as attribute or field) and not NULL, mustn’t exist in the table records belonging to that same tree.

static export($db, $forest_name[, $fields=NULL[, $tree_id=NULL]])¶

Create a JSON dump of one or more trees

Parameters:	$db (an instance of mysqli_connect) – mysqli database connection in object oriented style $forest_name (string) – name of the forest, equals to the name of the table holding the data $fields (array) – optional, the fields to be exported $tree_id (array or int) – optional, a single tree_id to be exported, or an array of them. If NULL all the trees in the table will be exported;
Returns:	a dump of the trees in JSON format
Return type:	string

Note

if ‘tree_id’ is passed as field, it will not appear in the field list because redundat (it will be present once in the tree_id attribute)

Example of an exported tree

[
 {
   "tree_id": 6,
   "fields" : ["id", "lft", "rgt"], // tree_id is stripped if requested via fields because redundant
   "values" :
       [1,1,4,[
           [2,2,3,[]]
       ]]
 }
 // more could follow ...
]

Table Of Contents

This Page

Baobab API¶

Copyright and License¶

Exceptions¶

Baobab¶

Navigation

Table Of Contents

This Page

Quick search

Baobab API¶

Copyright and License¶

Exceptions¶

Baobab¶