1. class
  2. phpbb
  3. \
  4. tree
  5. \
  6. nestedset

nestedset

abstract class nestedset implements tree_interface

Properties

protected driver_interface $db
protected db $lock
protected string $table_name
protected string $message_prefix

Prefix for the language keys returned by exceptions
protected string $column_item_id

Column names in the table
protected $column_left_id
protected $column_right_id
protected $column_parent_id
protected $column_item_parents
protected string $sql_where

Additional SQL restrictions Allows to have multiple nested sets in one table
protected array $item_basic_data

List of item properties to be cached in the item_parents column

Methods

__construct(driver_interface $db, db $lock, string $table_name, string $message_prefix = '', string $sql_where = '', array $item_basic_data = array(), array $columns = array())

Construct

string
get_sql_where(string $operator = 'AND', string $column_prefix = '')

Returns additional sql where restrictions

bool
acquire_lock()

Acquires a lock on the item table

array
insert(array $additional_data)

Inserts an item into the database table and into the tree.

array
add_item_to_nestedset(int $item_id)

Add an item which already has a database row at the end of the tree

array
remove_item_from_nestedset(int $item_id)

Remove an item from the tree without deleting it from the database

array
delete(int $item_id)

Delete an item from the tree and from the database table

bool
move(int $item_id, int $delta)

Move an item by a given delta

bool
move_down(int $item_id)

Move an item down by 1

bool
move_up(int $item_id)

Move an item up by 1

bool
move_children(int $current_parent_id, int $new_parent_id)

Moves all children of one item to another item

bool
change_parent(int $item_id, int $new_parent_id)

Change parent item

array
get_path_and_subtree_data(int $item_id, bool $order_asc = true, bool $include_item = true)

Get all items that are either ancestors or descendants of the item

array
get_path_data(int $item_id, bool $order_asc = true, bool $include_item = true)

Get all of the item's ancestors

array
get_subtree_data(int $item_id, bool $order_asc = true, bool $include_item = true)

Get all of the item's descendants

array
get_set_of_nodes_data(int $item_id, string $condition, bool $order_asc = true, bool $include_item = true)

Get items that are related to the given item by the condition

array
get_path_basic_data(array $item)

Get basic data of all parent items

array
get_all_tree_data(bool $order_asc = true)

Get all items from the tree

null
remove_subset(array $subset_items, array $bounding_item, bool $set_subset_zero = true)

Remove a subset from the nested set

int
prepare_adding_subset(array $subset_items, array $new_parent)

Prepare adding a subset to the nested set

array
reset_nestedset_values(array $item)

Resets values required for the nested set system

int
regenerate_left_right_ids(int $new_id, int $parent_id = 0, bool $reset_ids = false)

Regenerate left/right ids from parent/child relationship

Details

at line 67
__construct(driver_interface $db, db $lock, string $table_name, string $message_prefix = '', string $sql_where = '', array $item_basic_data = array(), array $columns = array())

Construct

Parameters

driver_interface $db

Database connection
db $lock

Lock class used to lock the table when moving forums around
string $table_name

Table name
string $message_prefix

Prefix for the messages thrown by exceptions
string $sql_where

Additional SQL restrictions for the queries
array $item_basic_data

Array with basic item data that is stored in item_parents
array $columns

Array with column names to overwrite

at line 96
string get_sql_where(string $operator = 'AND', string $column_prefix = '')

Returns additional sql where restrictions

Parameters

string $operator

SQL operator that needs to be prepended to sql_where, if it is not empty.
string $column_prefix

Prefix that needs to be prepended to column names

Return Value

string

Returns additional where statements to narrow down the tree, prefixed with operator and prepended column_prefix to column names

at line 108
protected bool acquire_lock()

Acquires a lock on the item table

Return Value

bool

True if the lock was acquired, false if it has been acquired previously

Exceptions

RuntimeException

at line 126
array insert(array $additional_data)

Inserts an item into the database table and into the tree.

Parameters

array $additional_data

The item to be added

Return Value

array

Array with item data as set in the database

at line 145
protected array add_item_to_nestedset(int $item_id)

Add an item which already has a database row at the end of the tree

Parameters

int $item_id

The item to be added

Return Value

array

Array with updated data, if the item was added successfully Empty array otherwise

at line 181
protected array remove_item_from_nestedset(int $item_id)

Remove an item from the tree without deleting it from the database

Also removes all subitems from the tree without deleting them from the database either

Parameters

int $item_id

The item to be deleted

Return Value

array

Item ids that have been removed

Exceptions

OutOfBoundsException

at line 205
array delete(int $item_id)

Delete an item from the tree and from the database table

Also deletes the subtree from the tree and from the database table

Parameters

int $item_id

The item to be deleted

Return Value

array

Item ids that have been deleted

at line 220
bool move(int $item_id, int $delta)

Move an item by a given delta

An item is only moved up/down within the same parent. If the delta is larger then the number of children, the item is moved to the top/bottom of the list of children within this parent.

Parameters

int $item_id

The item to be moved
int $delta

Number of steps to move this item, < 0 => down, > 0 => up

Return Value

bool

True if the item was moved

at line 338
bool move_down(int $item_id)

Move an item down by 1

Parameters

int $item_id

The item to be moved

Return Value

bool

True if the item was moved

at line 346
bool move_up(int $item_id)

Move an item up by 1

Parameters

int $item_id

The item to be moved

Return Value

bool

True if the item was moved

at line 354
bool move_children(int $current_parent_id, int $new_parent_id)

Moves all children of one item to another item

If the new parent already has children, the new children are appended to the list.

Parameters

int $current_parent_id

The current parent item
int $new_parent_id

The new parent item

Return Value

bool

True if any items where moved

at line 459
bool change_parent(int $item_id, int $new_parent_id)

Change parent item

Moves the item to the bottom of the new \parent's list of children

Parameters

int $item_id

The item to be moved
int $new_parent_id

The new parent item

Return Value

bool

True if the parent was set successfully

at line 557
array get_path_and_subtree_data(int $item_id, bool $order_asc = true, bool $include_item = true)

Get all items that are either ancestors or descendants of the item

Parameters

int $item_id

Id of the item to retrieve the ancestors/descendants from
bool $order_asc

Order the items ascendingly (most outer ancestor first)
bool $include_item

Should the item matching the given item id be included in the list as well

Return Value

array

Array of items (containing all columns from the item table) ID => Item data

at line 568
array get_path_data(int $item_id, bool $order_asc = true, bool $include_item = true)

Get all of the item's ancestors

Parameters

int $item_id

Id of the item to retrieve the ancestors from
bool $order_asc

Order the items ascendingly (most outer ancestor first)
bool $include_item

Should the item matching the given item id be included in the list as well

Return Value

array

Array of items (containing all columns from the item table) ID => Item data

at line 578
array get_subtree_data(int $item_id, bool $order_asc = true, bool $include_item = true)

Get all of the item's descendants

Parameters

int $item_id

Id of the item to retrieve the descendants from
bool $order_asc

Order the items ascendingly
bool $include_item

Should the item matching the given item id be included in the list as well

Return Value

array

Array of items (containing all columns from the item table) ID => Item data

at line 595
protected array get_set_of_nodes_data(int $item_id, string $condition, bool $order_asc = true, bool $include_item = true)

Get items that are related to the given item by the condition

Parameters

int $item_id

Id of the item to retrieve the node set from
string $condition

Query string restricting the item list
bool $order_asc

Order the items ascending by their left_id
bool $include_item

Should the item matching the given item id be included in the list as well

Return Value

array

Array of items (containing all columns from the item table) ID => Item data

at line 632
array get_path_basic_data(array $item)

Get basic data of all parent items

Basic data is defined in the $item_basic_data property. Data is cached in the item_parents column in the item table

Parameters

array $item

The item to get the path from

Return Value

array

Array of items (containing basic columns from the item table) ID => Item data

at line 676
array get_all_tree_data(bool $order_asc = true)

Get all items from the tree

Parameters

bool $order_asc

Order the items ascending by their left_id

Return Value

array

Array of items (containing all columns from the item table) ID => Item data

at line 705
protected null remove_subset(array $subset_items, array $bounding_item, bool $set_subset_zero = true)

Remove a subset from the nested set

Parameters

array $subset_items

Subset of items to remove
array $bounding_item

Item containing the right bound of the subset
bool $set_subset_zero

Should the parent, left and right id of the items be set to 0, or kept unchanged? In case of removing an item from the tree, we should the values to 0 In case of moving an item, we shouldkeep the original values, in order to allow "+ diff" later

Return Value

null

at line 747
protected int prepare_adding_subset(array $subset_items, array $new_parent)

Prepare adding a subset to the nested set

Parameters

array $subset_items

Subset of items to add
array $new_parent

Item containing the right bound of the new parent

Return Value

int

New right id of the parent item

at line 771
protected array reset_nestedset_values(array $item)

Resets values required for the nested set system

Parameters

array $item

Original item data

Return Value

array

Original item data + nested set defaults

at line 805
int regenerate_left_right_ids(int $new_id, int $parent_id = 0, bool $reset_ids = false)

Regenerate left/right ids from parent/child relationship

This method regenerates the left/right ids for the tree based on the parent/child relations. This function executes three queries per item, so it should only be called, when the set has one of the following problems:

  • The set has a duplicated value inside the left/right id chain
  • The set has a missing value inside the left/right id chain
  • The set has items that do not have a left/right id set

When regenerating the items, the items are sorted by parent id and their current left id, so the current child/parent relationships are kept and running the function on a working set will not change the order.

Parameters

int $new_id

First left_id to be used (should start with 1)
int $parent_id

parent_id of the current set (default = 0)
bool $reset_ids

Should we reset all left_id/right_id on the first call?

Return Value

int

$new_id The next left_id/right_id that should be used