Documentation

save($cascade = null, $use_transaction = false)

The save method works exactly the same as the regular model's implementation.

However, when you use this method on new tree node objects, additional functionality is added to make sure the tree structure stays consistent. When you call it on an object and you have used one of the collection methods documented below, the new object is inserted in the tree relative to the object passed to the collection method.

If you haven't used a collection method, save will assume you want to insert a new root node. If the model is a multi-tree model, it will create a new root with the next available tree-id (if the id is numeric. If not, assign a new tree-id to the node object yourself).

If a root node can not be created because one already exists, an OutOfBoundsException will be thrown. If the tree-id is not numeric, and you haven't supplied one manually, the result is unpredicable!

delete($cascade = null, $use_transaction = false)

The delete method works exactly the same as the regular model's implementation.

If the node you delete is not a leaf node (i.e. is has children), all descendants of the node will move one level up in the tree, they will become descendants of the nodes parent. If you want to delete an entire (subsection of the) tree, use the delete_tree() method instead.

You can not use the delete() method on a root node if the root node has more then one child node. Doing so would create an inconsistent tree, as you can't have multiple nodes at the highest level. Trying do to so will throw a DomainException!

root()

The root method allows you to get the root of the tree of the object you call this method on.

// get the root of the tree $henry belongs to
$root = $henry->root()->get_one();

// 'true' を echo
echo $root == $bill ? 'true' : 'false';

// 特定のツリーのルートを取得
$root = Model_Tree::forge()->set_tree_id($mytreeid)->root()->get_one();

roots()

The roots method allows you to get all the root nodes. If the model is not a multi-tree model, only the one root node is returned.

// get all roots in the tree
$roots = $henry->roots()->get();

// 'true' を echo （このツリー内には 1 つのルートだけがある）
echo reset($roots) == $bill ? 'true' : 'false';

// 既存のオブジェクトを起点とせずにすべてのルートを取得
$roots = Model_Tree::forge()->roots()->get();

parent()

The parent method allows you to get the parent node of the object you call this method on.

// get the parent of $nicola
$parent = $nicola->parent()->get_one();

// 'true' を echo
echo $parent == $angela ? 'true' : 'false';

// null が返る。ノードのツリーコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->parent()->get_one();

children()

The children method allows you to get all child nodes of the object you call this method on. Note that this returns only children, no grandchildren. If you are interested in the entire sub-tree, use the descendants method instead.

// get the children of $angela
$children = $angela->children()->get();

// 'true' を echo
echo $children == array($henry->id => $henry, $nicola->id => $nicola) ? 'true' : 'false';

// null が 返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->children()->get();

ancestors()

The ancestors method allows you to get all ancestor nodes of the object you call this method on.

// get the ancestors of $henry
$ancestors = $henry->children()->get();

// 'true' を echo
echo $ancestors == array($bill->id => $bill, $angela->id => $angela) ? 'true' : 'false';

// null が返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->ancestors()->get();

Ancestors are returned in order of their position in the tree, with the root node first.

descendants()

The descendants method allows you to get all descendant nodes of the object you call this method on. This allows you to fetch an entire sub-tree.The result will NOT include the start node itself.

// get the descendants of $ben
$descendants = $ben->descendants()->get();

// 'true' を echo
echo $descendants == array($kerry->id => $kerry, $tim->id => $tim, $james->id => $james) ? 'true' : 'false';

// null が返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->descendants()->get();

Descendants are returned in order of their position in the tree.

leaf_descendants()

The leaf_descendants method allows you to get leaf descendant nodes of the object you call this method on. Unlike the descendants method, this method only returns nodes that do not have children (the leafs of the tree).

// get the leaf descendants of $ben
$descendants = $ben->leaf_descendants()->get();

// 'true' を echo。$kerry は子のオブジェクトを持つため、ここでは返されないことに注意
echo $descendants == array($tim->id => $tim, $james->id => $james) ? 'true' : 'false';

// null が返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->leaf_descendants()->get();

Leaf descendants are returned in order of their position in the tree.

siblings()

The siblings method allows you to get all sibling nodes of the object you call this method on.

// get the siblings of $kerry
$siblings = $kerry->siblings()->get();

// 'true' を echo
echo $siblings == array($kerry->id => $kerry, $james->id => $james) ? 'true' : 'false';

// null が返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->siblings()->get();

Siblings are returned in order of their position in the tree. Note that the result set will include the current node!

child()

The child method is an alias for the last_child method.

first_child()

The first_child method allows you to get the first child node of the object you call this method on.

// get the first child of $bill
$child = $bill->first_child()->get_one();

// 'true' を echo
echo $child == $angela ? 'true' : 'false';

// null が 返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->first_child()->get_one();

last_child()

The last_child method allows you to get the last child node of the object you call this method on.

// get the last child of $bill
$child = $bill->last_child()->get_one();

// 'true' を echo
echo $child == $ben ? 'true' : 'false';

// null が返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->last_child()->get_one();

sibling()

The sibling method is an alias for the next_sibling method.

previous_sibling()

The previous_sibling method allows you to get the previous_sibling node of the object you call this method on.

// get the previous sibling of $nicola
$sibling = $nicola->previous_silbing()->get_one();

// 'true' を echo
echo $sibling == $henry ? 'true' : 'false';

// null が返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->previous_sibling()->get_one();

// こちらも null が返る。$henry には前の兄弟がない
$sibling = $henry->previous_silbing()->get_one();

next_sibling()

The next_sibling method allows you to get the next sibling node of the object you call this method on.

// get the next sibling of $henry
$sibling = $henry->next_silbing()->get_one();

// 'true' を echo
echo $sibling == $nicola ? 'true' : 'false';

// null が返る。現在のノードのコンテキストがなければうまくいかない
$parent = Model_Tree::forge()->previous_sibling()->get_one();

// こちらも null が返る。$nicola には次の兄弟がない
$sibling = $nicola->next_silbing()->get_one();

path($addroot = true)

The path method returns the path to the current node as a string, using the column identified by the "title_field" in the models tree configuration.

true

// get the path to Tim, returns "Bill/Ben/Kerry/Tim"
$path = $tim->path()->get();

// Nicola までのパスを取得。"Bill/Angela/Nicola" を返す
$path = $nicola->path()->get();

// Kerry までのパスを取得。ボスについては除外。"Ben/Kerry" を返す
$path = $kerry->path(false)->get();

child($to = null)

The child method is an alias for the last_child method.

first_child($to = null)

The first_child method tells the model you want to save the object you call this method on as the first child of the (primary key of the) node object passed.

null

// give bill a new subordinate, before Angela in the tree
$john = Model_Tree::forge(array('name' => 'John'))->first_child($bill)->save();

// Kerry を Bill の部下に昇進させる
$kerry->first_child($bill)->save();

last_child($to = null)

The last_child method tells the model you want to save the object you call this method on as the last child of the (primary key of the) node object passed.

null

// give bill a new subordinate, after Ben in the tree
$john = Model_Tree::forge(array('name' => 'John'))->last_child($bill)->save();

// Kerry を Bill の部下に昇進させる
$kerry->last_child($bill)->save();

sibling($to = null)

The sibling method is an alias for the next_sibling method.

previous_sibling($to = null)

The previous_sibling method tells the model you want to save the object you call this method on as the previous sibling of the (primary key of the) node object passed (just before the passed object, on the same level in the tree).

null

// give bill a new subordinate, before Angela in the tree
$john = Model_Tree::forge(array('name' => 'John'))->previous_sibling($angela)->save();

// James を Ben の部下、Tim の隣へ降格させる
$james->previous_sibling($tim)->save();

next_sibling($to = null)

The next_sibling method tells the model you want to save the object you call this method on as the next sibling of the (primary key of the) node object passed (just after the passed object, on the same level in the tree).

null

// give bill a new subordinate, after Angela in the tree
$john = Model_Tree::forge(array('name' => 'John'))->next_sibling($angela)->save();

// James を Ben の部下、Tim の隣へ降格させる
$james->next_sibling($tim)->save();

is_root()

The is_root method tells you if the object you're calling it on is a root node or not.

// is Bill a root node? echo's 'true'
echo $bill->is_root() ? 'true' : 'false';

// Tim がルートノードか？ 'false' を echo
echo $tim->is_root() ? 'true' : 'false';

is_leaf()

The is_leaf method tells you if the object you're calling it on is a leaf, i.e. that is doesn't have child nodes.

// is Tim a leaf node? echo's 'true'
echo $tim->is_leaf() ? 'true' : 'false';

// Angela が末端ノードか？ 'false' を echo
echo $angela->is_leaf() ? 'true' : 'false';

is_child()

The is_child method tells you if the object you're calling it on is a child node, i.e. that is has a parent node. This is the reverse of is_root(), as all non-root nodes have a parent.

// is Henry a root node? echo's 'true'
echo $henry->is_child() ? 'true' : 'false';

// Bill がルートノードか？ 'false' を echo
echo $bill->is_child() ? 'true' : 'false';

is_child_of(Model_Nestedset $to = null)

The is_child_of method allows you to check if the object you call this method on is a child node (a direct descendant) of the node object passed.

null

// is Ben a child node of Bill? echo's 'true'
echo $ben->is_child_of($bill) ? 'true' : 'false';

// James が Bill の子ノードか？ 孫なので 'false' を echo
echo $james->is_child_of($bill) ? 'true' : 'false';

// Nicola が Ben の子ノードか？ ツリーの違う部分なので 'false' を echo
echo $nicola->is_child_of($ben) ? 'true' : 'false';

is_descendant_of(Model_Nestedset $to = null)

The is_descendant_of method allows you to check if the object you call this method on is a descendant node of the node object passed.

null

// is Ben a descendant node of Bill? echo's 'true'
echo $ben->is_descendant_of($bill) ? 'true' : 'false';

// James が Bill の子孫ノードか？ 孫なので 'true' を echo
echo $james->is_descendant_of($bill) ? 'true' : 'false';

// Nicola が Ben の子孫ノードか？ ツリーの別の部分なので 'false' を echo
echo $nicola->is_descendant_of($ben) ? 'true' : 'false';

is_parent_of(Model_Nestedset $to = null)

The is_parent_of method allows you to check if the object you call this method on is the parent node of the node object passed.

null

// is Bill the parent of Ben? echo's 'true'
echo $bill->is_parent_of($ben) ? 'true' : 'false';

// Bill が James の親か？ 祖父なので 'false' を echo
echo $bill->is_parent_of($james) ? 'true' : 'false';

is_ancestor_of(Model_Nestedset $to = null)

The is_ancestor_of method allows you to check if the object you call this method on is a ancestor of the node object passed.

null

// is Bill an ancestor of Ben? echo's 'true'
echo $bill->is_ancestor_of($ben) ? 'true' : 'false';

// Bill が James の祖先か？ 祖父なので 'true' を echo
echo $bill->is_ancestor_of($james) ? 'true' : 'false';

is_same_model_as(Model_Nestedset $to = null)

This method is mainly used internally to avoid operations across two different Nestedset models.

is_same_tree_as(Model_Nestedset $to = null)

This method is mainly used internally to avoid operations across two different Nestedset models. It not only checks if both objects are instances of the same model, but also if both instances belong to the same tree in a multi-tree model.

has_parent()

The has_parent method is an alias for the is_child method.

has_children()

The has_children method is the reverse of the is_leaf method. If an object is not a leaf, it implies it has child nodes.

has_previous_sibling()

The has_previous_sibling method tells you if the object you're calling it on has a previous sibling.

// Does James have a previous sibling? echo's 'true'
echo $james->has_previous_sibling() ? 'true' : 'false';

// Tim が前の兄弟を持つか？ 'false' を echo
echo $tim->has_previous_sibling() ? 'true' : 'false';

has_next_sibling()

The has_next_sibling method tells you if the object you're calling it on has a next sibling.

// Does Henry have a next sibling? echo's 'true'
echo $henry->has_next_sibling() ? 'true' : 'false';

// Ben が次の兄弟を持つか？ 'false' を echo
echo $ben->has_next_sibling() ? 'true' : 'false';

delete_tree($cascade = null, $use_transaction = false)

The delete_tree works identical to the delete() method, which the difference that this method DOES delete all children as well.

If you use the delete_tree() method on a root node, the entire tree will be deleted!

tree_config($name = null)

You use this method to get one or all tree configuration options of the model. It is mainly used internally to construct queries that operate on parts of the tree, or on a specific tree in a multi-tree model.

null

// get the name of the tree-id column
$tree_id = Model_Tree::tree_config('tree_id');

get_tree_id()

You use this method to get the tree-id in a multi-tree environment. If there is a valid node to operate on, the tree-id of that node is returned. If not, the value set using set_tree_id() is returned. If no tree-id has been set, an exception is thrown. This method is mainly used internally to make sure queries run in the context of the current tree in a multi-tree environment.

// get the tree_id (returns 1)
$current_tree = $bill->get_tree_id();

set_tree_id($tree = null)

You use this method to set the tree-id in a multi-tree environment. You mainly use this when you want to run a get() or get_one() but you don't have an existing node to work on.

null

// get the root of a tree without having a previous node to work with
$root = Model_Tree::forge()->set_tree_id($mytreeid)->get_one();

build_query()

The build_query method returns an ORM query object, like Model_Nestedset::query() but with an added where clause in case of a multi-tree model, to make sure the query runs in the context of the current tree. It requires a tree-id to be available, so if you call this on a new object, use set_tree_id to make sure a valid id is defined.

// get all nodes in the current tree with an enabled status set
$enabled = Model_Tree::forge()
	->set_tree_id($mytreeid)
	->build_query()
	->where('enabled', '=', 1)
	->get();

// 既存のオブジェクトを使う場合。$bill のオブジェクトのツリー ID が使われる
$enabled = $bill
	->build_query()
	->where('enabled', '=', 1)
	->get();

get_query()

The get_query method returns an ORM query object, but unlike build_query() this method requires a collection methods to be used. It allows you to use the standard Model methods to constuct a first selection of nodes, and use the returned Query object to fine-tune the query.

// get all child nodes of Bill with an enabled status set
$enabled = $bill
	->children()
	->get_query()
	->where('enabled', '=', 1)
	->get();

count_children()

The count_children method returns the number of children (direct descendants) of the object you're calling it on.

// Get the number of Bill's children, echo's 2
echo $bill->count_children();

// Kerry の子の数を取得。1 を echo
echo $kerry->count_children();

// Tim の子の数を取得。0 を echo
echo $tim->count_children();

// これも 0 を echo。新たなオブジェクトは子を持たない
echo Model_Tree::forge()->count_children();

count_descendants()

The count_descendants method returns the number of descendants of the object you're calling it on.

// Get the number of Bill's descendants, echo's 7
echo $bill->count_descendants();

// Ben の子の数を取得。3 を echo
echo $ben->count_descendants();

// 0 を echo。新たなオブジェクトは子孫を持たない
echo Model_Tree::forge()->count_descendants();

depth()

The depth method returns the depth or level the current node is in the tree, where the level of the root node is 0.

// Get the level of Bill in the organisation
echo $bill->depth(); // echo's 0, he's top dog!

// 組織内での Angela の階級を取得
echo $angela->depth(); // 1 を echo。彼女は N+1 のため

// 組織内での Tim の階級を取得
echo $tim->depth(); // 3 を echo。いちばんの下っ端だ……

// 偽を返す。新たなノードの階層を取得することはできない
$result = Model_Tree::forge()->depth();

dump_tree($as_object = false, $children = 'children', $path = 'path', $pathuri = null)

The dump_tree method returns the entire tree, using the current object as root node into a multi-dimensional array.

false

'children'

'path'

null

// returns a multi-dimensional array. $tree['children'] will contain the children of Bill
$tree = $bill->dump_tree();

// 'children' プロパティとして Bill の子を持つ 'bill' オブジェクトを返す
$tree = $bill->dump_tree(true);

// $tree を使うと、array($angela, $ben) を返す
$children = $tree->children;

// そしてこちらは array($henry, $nicola)、つまり $angela の子を返す
$grandchildren = reset($children)->children;

// ORM オブジェクトは常に参照として扱われる！
$bill->dump_tree(true);

// ので、こっちでもいける
$children = $bill->children;

As with all ORM array's, the table's primary key is used as array index. Note that because the ORM uses objects by reference from a single cache, if you choose to use 'as_object', children will be added to existing objects too.

related($relation, $conditions = array())

The related method allows you to fetch related objects when executing a nested set command, indentical to a normal Orm model query.

required

array()

// include related 'child' objects in the result
$tree = $bill->related('child')->dump_tree();

// $ben の子孫を取得
$descendants = $ben->descendants()->related('child')->get();

// これには child のリレーションは含まれ「ない」！
$descendants = $ben->related('child')->descendants()->get();

If you want to use this method on any nested set operation (like for example decendants()), make sure to setup that operation first. If you don't, your included relations will be reset my the nested set operation method call!