Zebra_Mptt Zebra_Mptt

Class: Zebra_Mptt

source file: /Zebra_Mptt.php

A PHP library that provides an implementation of the modified preorder tree traversal algorithm making it easy to implement the MPTT algorithm in your PHP applications.

Read more here

Author(s):

Version:

  • 2.3.7 (last revision: April 26, 2022)
    See CHANGELOG

License:

Copyright:

  • (c) 2009 - 2022 Stefan Gabos

Class methods

constructor __construct()

Constructor of the class.

Make sure that before you instantiate the class you import or execute the SQL code found in the in the install/mptt.sql file, using the command line or your preferred MySQL manager.

  1. // include the php file
  2. require 'path/to/Zebra_Mptt.php';
  3.  
  4. // instantiate the class
  5. $mptt new Zebra_Mptt($db_link);

void __construct ( resource &$link , [ string $table_name = 'mptt' ] , [ string $id_column = 'id' ] , [ string $title_column = 'title' ] , [ string $left_column = 'lft' ] , [ string $right_column = 'rgt' ] , [ string $parent_column = 'parent' ] )

Arguments
resource &$link

An object representing the connection to a MySQL Server, as returned by mysqli_connect.

If you use Zebra_Database to connect to the database, you can get the connection to the MySQL server via Zebra_Database's get_link method.

string $table_name

(Optional) MySQL table name to be used for storing items.

Default is mptt

string $id_column

(Optional) Name of the column that uniquely identifies items in the table

Default is id

string $title_column

(Optional) Name of the column that stores item names

Default is title

string $left_column

(Optional) Name of the column that stores "left" values

Default is lft ("left" is a reserved word in MySQL)

string $right_column

(Optional) Name of the column that stores "right" values

Default is rgt ("right" is a reserved word in MySQL)

string $parent_column

(Optional) Name of the column that stores the IDs of parent items

Default is parent

top

method add()

Adds a new node as the child of a given parent node.

  1. // add a new topmost node
  2. $node $mptt->add(0'Main');
  3.  
  4. // add a child node
  5. $mptt->add($node'Child 1');
  6.  
  7. // add another child node
  8. $mptt->add($node'Child 2');
  9.  
  10. // insert a third child node
  11. // notice the "1" as the last argument, instructing the script to insert the child node
  12. // as the second child node, after "Child 1"
  13. // remember that the trees are 0-based, meaning that the first node in a tree has the index 0!
  14. $mptt->add($node'Child 3'1);
  15.  
  16. // and finally, insert a fourth child node
  17. // notice the "0" as the last argument, instructing the script to insert the child node
  18. // as the very first child node of the parent node
  19. // remember that the trees are 0-based, meaning that the first node in a tree has the index 0!
  20. $mptt->add($node'Child 4'0);

mixed add ( integer $parent , string $title , [ integer $position = false ] )

Arguments
integer $parent

The ID of the parent node.

Use 0 to add a topmost node.

string $title The title of the node.
integer $position

(Optional) The position the node will have among the parent node's children nodes.

When parent node is given as 0, this refers to the position the node will have among the topmost nodes.

The values are 0-based, meaning that if you want the node to be inserted as the first child of the target node, you have to use 0, if you want it to be second, use 1, and so on.

If not given (or given as boolean FALSE), the node will be inserted as the last of the parent node's children nodes.

Tags
return:   Returns the ID of the newly inserted node or FALSE on error.
top

method copy()

Creates a copy of a node (including its descendant nodes) as the child node of a given node.

  1. // insert a topmost node
  2. $node $mptt->add(0'Main');
  3.  
  4. // add a child node
  5. $child1 $mptt->add($node'Child 1');
  6.  
  7. // add another child node
  8. $child2 $mptt->add($node'Child 2');
  9.  
  10. // create a copy of "Child 2" node and put it as "Child 1"'s child
  11. $mptt->copy($child2$child1);

mixed copy ( integer $source , integer $target , [ integer $position = false ] )

Arguments
integer $source

The ID of a node to copy.

Remember that the node will be copied together with all its descendant nodes!

integer $target

The ID of a node which will become the copy's parent node.

Use 0 to make the copy a topmost node.

integer $position

(Optional) The position the node will have among the target node's children nodes.

When target node is 0, this refers to the position the node will have among the topmost nodes.

The values are 0-based, meaning that if you want the node to be inserted as the first child of the target node, you have to use 0, if you want it to be second, use 1, and so on.

If not given (or given as boolean FALSE), the node will be inserted as the last of the target node's children nodes.

Tags
return:   Returns the ID of the newly created copy, or FALSE on error.
top

method delete()

Deletes a node, including the node's descendant nodes.

  1. // add a topmost node
  2. $node $mptt->add(0'Main');
  3.  
  4. // add child node
  5. $child1 $mptt->add($node'Child 1');
  6.  
  7. // add another child node
  8. $child2 $mptt->add($node'Child 2');
  9.  
  10. // delete the "Child 2" node
  11. $mptt->delete($child2);

boolean delete ( integer $node )

Arguments
integer $node The ID of the node to delete.
Tags
return:   TRUE on success or FALSE on error.
top

method get_descendants()

Returns an unidimensional (flat) array with the descendant nodes of a given parent node.

For a multidimensional array use the get_tree() method.

array get_descendants ( [ integer $node = 0 ] , [ boolean $direct_descendants_only = true ] )

Arguments
integer $node

(Optional) The ID of a node for which to return the descendant nodes.

When not specified or given as 0, the root node is implied.

boolean $direct_descendants_only

(Optional) Set this to FALSE if you want all the descendants (including descendants of descendants), and not just the direct descendants (children) of the node.

Default is TRUE

Tags
return:   Returns an unidimensional array with the descendant nodes of a given parent node.
top

method get_descendant_count()

Returns the number of descendant nodes of a given node.

integer get_descendant_count ( integer $node , [ boolean $direct_descendants_only = true ] )

Arguments
integer $node The ID of the node for which to return the number of direct descendant nodes.
boolean $direct_descendants_only

(Optional) Specifies whether to count direct descendants only, or to count all the descendants (including descendants of descendants)

Default is TRUE

Tags
return:  

Returns the number of direct descendant nodes of a parent node, or FALSE on error.

Since this method may return both 0 and FALSE, make sure you use === to verify the returned result!

top

method get_next_sibling()

Returns the next sibling of a node.

mixed get_next_sibling ( integer $node )

Arguments
integer $node The ID of a node for which to return the next sibling node.
Tags
return:  

Returns a node's next sibling node, 0 if a next sibling doesn't exist, or FALSE on error (if the node doesn't exist).

Since this method may return both 0 and FALSE, make sure you use === to verify the returned result!

since:   2.2.6
top

method get_parent()

Returns an array containing a node's direct parent node if the node has a parent node, or 0 if the node is a topmost node.

mixed get_parent ( integer $node )

Arguments
integer $node The ID of a node for which to return the parent node.
Tags
return:  

Returns an array containing a node's direct parent node if the node has a parent node, or 0 if the node is a topmost node.

Since this method may return both 0 and FALSE, make sure you use === to verify the returned result!

top

method get_path()

Returns an unidimensional (flat) array with the path to the given node (including the node itself).

array get_path ( integer $node )

Arguments
integer $node The ID of a node for which to return the path.
Tags
return:   Returns an unidimensional array with the path to the given node.
top

method get_previous_sibling()

Returns the previous sibling of a node.

mixed get_previous_sibling ( integer $node )

Arguments
integer $node The ID of a node for which to return the previous sibling node.
Tags
return:  

Returns a node's previous sibling node, 0 if a previous sibling doesn't exist, or FALSE on error (if the node doesn't exist).

Since this method may return both 0 and FALSE, make sure you use === to verify the returned result!

since:   2.2.6
top

method get_siblings()

Returns an array with a node's sibling nodes.

mixed get_siblings ( integer $node , [ boolean $include_self = false ] )

Arguments
integer $node The ID of a node for which to return the node's sibling nodes.
boolean $include_self Whether the node given as argument should also be present in the returned array.
Tags
return:   Returns an array with a node's sibling nodes, an empty array if the node has no siblings, or FALSE on error (if the node doesn't exist)
since:   2.2.6
top

method get_tree()

Returns a multidimensional array with all the descendant nodes (including children nodes of children nodes of children nodes and so on) of a given node.

array get_tree ( [ integer $node = 0 ] )

Arguments
integer $node

(Optional) The ID of a node for which to return all descendant nodes, as a multidimensional array.

Not given or given as 0, will return all the nodes.

Tags
return:   Returns a multi dimensional array with all the descendant nodes (including children nodes of children nodes of children nodes and so on) of a given node.
top

method move()

Moves a node, including the node's descendants nodes, into another node (becoming that node's child), or after/before a node (becoming that node's sibling)

  1. // insert a topmost node
  2. $node $mptt->add(0'Main');
  3.  
  4. // add a child node
  5. $child1 $mptt->add($node'Child 1');
  6.  
  7. // add another child node
  8. $child2 $mptt->add($node'Child 2');
  9.  
  10. // add another child node
  11. $child3 $mptt->add($node'Child 3');
  12.  
  13. // move "Child 2" node to be the first of "Main"'s children nodes
  14. $mptt->move($child2$node0);
  15.  
  16. // move "Child 2" node into "Child 1"
  17. $mptt->move($child2$child1);
  18.  
  19. // move "Child 1" after "Child 3"
  20. $mptt->move($child1$child3'after');

boolean move ( integer $source , integer $target , [ integer $position = false ] )

Arguments
integer $source The ID of a node to move
integer $target The ID of the node relative to which the source node needs to be moved. Use 0 if the node does not need a parent node (making it a topmost node).
integer $position

(Optional) The position where to move the node, relative to the target node.

Can be a numerical value, indicating that the source node needs to be moved to become a child of the target node, inserted at the indicated position ( the values are 0-based, meaning that if you want the node to be inserted as the first child of the target node, you have to use 0, if you want it to be second, use 1, and so on)

Can also be the literal after or before string, indicating the the source node needs to be moved after/before the target node.

If not given (or given as boolean FALSE), the node will be inserted as the last of the target node's children nodes.

Tags
return:   TRUE on success or FALSE on error
top

method to_list()

Transforms a node and it's subnodes to an ordered/unordered list.

The list items will have the class attribute set to zebra_mptt_item zebra_mptt_item_xx where xx is the ID of the respective node.

You can further customize the output with regular expressions to suit your needs

  1. // instantiate the class
  2. $mptt new Zebra_Mptt();
  3.  
  4. // make a list out of all nodes as an ordered list and with the
  5. // main list having the class "mylist"
  6. echo $mptt->to_list(0'ol''class="mylist"');

string to_list ( integer $node , [ string $list_type = 'ul' ] , [ string $attributes = '' ] )

Arguments
integer $node

The ID of a node.

When given as 0, the root node is implied.

string $list_type

(Optional) Can be either ul (for an unordered list) or ol (for an ordered list).

Default is ul.

string $attributes Additional HTML attributes to set for the main list, like class or style.
Tags
since:   2.2.3
top

method to_select()

Returns an unidimensional (flat) array with the descendant nodes of the node given as argument, indented using whatever given in the $separator argument, and ready to be used in a <select> element.

  1. $selectables $mptt->to_select($node_id);
  2.  
  3. echo '<select name="myselect">';
  4.  
  5. foreach ($selectables as $value => $caption)
  6.  
  7.     echo '<option value="' $value '">' $caption '</option>';
  8.  
  9. echo '</select>';

array to_select ( [ integer $node = 0 ] , [ string $separator = ' &rarr; ' ] , [ boolean $show_full_path = false ] )

Arguments
integer $node

(Optional) The ID of a node for which to get the descendant nodes and return everything as a unidimensional (flat) array, indented using whatever given in the $separator argument, and ready to be used in a <select> control.

When not given, or given as 0, will return an array with all the available nodes.

string $separator

(Optional) A string used to separate nodes.

Default is &rarr;

boolean $show_full_path

(Optional) By default, parent nodes are not shown.

Set this to TRUE to show full path to each node.

Default is FALSE.

This option was added in 2.3.6

Tags
return:   Returns an array of children nodes of a node given as argument, indented and ready to be used in a <select> control.
top

method update()

Updates a node's title.

  1. // add a topmost node
  2. $node $mptt->add(0'Main');
  3.  
  4. // change the node's title
  5. $mptt->update($node'Primary');

boolean update ( integer $node , string $title )

Arguments
integer $node The ID of a node to update the title for.
string $title The new title to be set for the node.
Tags
return:   TRUE on success or FALSE on error.
since:   2.2.5
top