1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\tree;
15
16	interface tree_interface
17	{
18	/**
19	* Inserts an item into the database table and into the tree.
20	*
21	* @param array    $additional_data    The item to be added
22	* @return array Array with item data as set in the database
23	*/
24	public function insert(array $additional_data);
25
26	/**
27	* Delete an item from the tree and from the database table
28	*
29	* Also deletes the subtree from the tree and from the database table
30	*
31	* @param int    $item_id    The item to be deleted
32	* @return array        Item ids that have been deleted
33	*/
34	public function delete($item_id);
35
36	/**
37	* Move an item by a given delta
38	*
39	* An item is only moved up/down within the same parent. If the delta is
40	* larger then the number of children, the item is moved to the top/bottom
41	* of the list of children within this parent.
42	*
43	* @param int    $item_id    The item to be moved
44	* @param int    $delta        Number of steps to move this item, < 0 => down, > 0 => up
45	* @return bool True if the item was moved
46	*/
47	public function move($item_id, $delta);
48
49	/**
50	* Move an item down by 1
51	*
52	* @param int    $item_id    The item to be moved
53	* @return bool True if the item was moved
54	*/
55	public function move_down($item_id);
56
57	/**
58	* Move an item up by 1
59	*
60	* @param int    $item_id    The item to be moved
61	* @return bool True if the item was moved
62	*/
63	public function move_up($item_id);
64
65	/**
66	* Moves all children of one item to another item
67	*
68	* If the new parent already has children, the new children are appended
69	* to the list.
70	*
71	* @param int    $current_parent_id    The current parent item
72	* @param int    $new_parent_id        The new parent item
73	* @return bool True if any items where moved
74	*/
75	public function move_children($current_parent_id, $new_parent_id);
76
77	/**
78	* Change parent item
79	*
80	* Moves the item to the bottom of the new \parent's list of children
81	*
82	* @param int    $item_id            The item to be moved
83	* @param int    $new_parent_id        The new parent item
84	* @return bool True if the parent was set successfully
85	*/
86	public function change_parent($item_id, $new_parent_id);
87
88	/**
89	* Get all items that are either ancestors or descendants of the item
90	*
91	* @param int        $item_id        Id of the item to retrieve the ancestors/descendants from
92	* @param bool        $order_asc        Order the items ascendingly (most outer ancestor first)
93	* @param bool        $include_item    Should the item matching the given item id be included in the list as well
94	* @return array            Array of items (containing all columns from the item table)
95	*                            ID => Item data
96	*/
97	public function get_path_and_subtree_data($item_id, $order_asc, $include_item);
98
99	/**
100	* Get all of the item's ancestors
101	*
102	* @param int        $item_id        Id of the item to retrieve the ancestors from
103	* @param bool        $order_asc        Order the items ascendingly (most outer ancestor first)
104	* @param bool        $include_item    Should the item matching the given item id be included in the list as well
105	* @return array            Array of items (containing all columns from the item table)
106	*                            ID => Item data
107	*/
108	public function get_path_data($item_id, $order_asc, $include_item);
109
110	/**
111	* Get all of the item's descendants
112	*
113	* @param int        $item_id        Id of the item to retrieve the descendants from
114	* @param bool        $order_asc        Order the items ascendingly
115	* @param bool        $include_item    Should the item matching the given item id be included in the list as well
116	* @return array            Array of items (containing all columns from the item table)
117	*                            ID => Item data
118	*/
119	public function get_subtree_data($item_id, $order_asc, $include_item);
120	}