Package: Zebra_Mptt

Class: Zebra_Mptt

source file: /Zebra_Mptt.php

Class Overview


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.5 (last revision: July 14, 2017)

Copyright:

  • (c) 2009 - 2017 Stefan Gabos

Class methods

constructor __construct()

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'] )

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);
Tags:
access: public
Parameters:
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()

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

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);
Tags:
return: Returns the ID of the newly inserted node or FALSE on error.
access: public
Parameters:
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.

top

method copy()

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

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);
Tags:
return: Returns the ID of the newly created copy, or FALSE on error.
access: public
Parameters:
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.

top

method delete()

boolean delete ( integer $node )

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);
Tags:
return: TRUE on success or FALSE on error.
access: public
Parameters:
integer $node The ID of the node to delete.
top

method get_descendants()

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

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

For a multidimensional array use the get_tree() method.

Tags:
return: Returns an unidimensional array with the descendant nodes of a given parent node.
access: public
Parameters:
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

top

method get_descendant_count()

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

Returns the number of descendant nodes of a given node.

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!

access: public
Parameters:
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

top

method get_next_sibling()

mixed get_next_sibling ( integer $node )

Returns the next sibling of a 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
access: public
Parameters:
integer $node The ID of a node for which to return the next sibling node.
top

method get_parent()

mixed get_parent ( integer $node )

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.

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.

access: public
Parameters:
integer $node The ID of a node for which to return the parent node.
top

method get_path()

array get_path ( integer $node )

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

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

method get_previous_sibling()

mixed get_previous_sibling ( integer $node )

Returns the previous sibling of a 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
access: public
Parameters:
integer $node The ID of a node for which to return the previous sibling node.
top

method get_siblings()

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

Returns an array with a node's sibling nodes.

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
access: public
Parameters:
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.
top

method get_tree()

array get_tree ( [ integer $node = 0] )

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.

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.
access: public
Parameters:
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.

top

method move()

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

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');
Tags:
return: TRUE on success or FALSE on error
access: public
Parameters:
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.

top

method to_list()

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

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"');
Tags:
since: 2.2.3
access: public
Parameters:
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".
top

method to_select()

array to_select ( [ integer $node = 0] , [ string $separator = ' → '] )

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->get_selectables($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>';
Tags:
return: Returns an array of children nodes of a node given as argument, indented and ready to be used in a <select> control.
access: public
Parameters:
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 to indent the nodes by.

Default is " &rarr; "

top

method update()

boolean update ( integer $node , string $title )

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');
Tags:
return: TRUE on success or FALSE on error.
since: 2.2.5
access: public
Parameters:
integer $node The ID of a node to update the title for.
string $title The new title to be set for the node.
top