From a1183a58894967bfec7da01c5004138e4daeb583 Mon Sep 17 00:00:00 2001
From: Joas Schilling <nickvergessen@gmx.de>
Date: Tue, 16 Apr 2013 23:07:48 +0200
Subject: [PATCH] [ticket/11495] Add basic interface with nestedset operations

PHPBB3-11495
---
 phpBB/includes/nestedset/interface.php      | 131 ++++++++++++++++++++
 phpBB/includes/nestedset/item/interface.php |  61 +++++++++
 2 files changed, 192 insertions(+)
 create mode 100644 phpBB/includes/nestedset/interface.php
 create mode 100644 phpBB/includes/nestedset/item/interface.php

diff --git a/phpBB/includes/nestedset/interface.php b/phpBB/includes/nestedset/interface.php
new file mode 100644
index 0000000000..7ef6ff87bb
--- /dev/null
+++ b/phpBB/includes/nestedset/interface.php
@@ -0,0 +1,131 @@
+<?php
+/**
+*
+* @package Nested Set
+* @copyright (c) 2013 phpBB Group
+* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
+*
+*/
+
+/**
+* @ignore
+*/
+if (!defined('IN_PHPBB'))
+{
+	exit;
+}
+
+interface phpbb_nestedset_interface
+{
+	/**
+	* Insert an item into the nested set (also insert the rows into the table)
+	*
+	* @param phpbb_nestedset_item_interface	$item	The item to be added
+	* @return array Array with item data as set in the database
+	*/
+	public function insert(array $additional_data);
+
+	/**
+	* Add an item at the end of the nested set
+	*
+	* @param phpbb_nestedset_item_interface	$item	The item to be added
+	* @return bool True if the item was added
+	*/
+	public function add(phpbb_nestedset_item_interface $item);
+
+	/**
+	* Remove an item from the nested set
+	*
+	* Also removes all subitems from the nested set
+	*
+	* @param phpbb_nestedset_item_interface	$item	The item to be removed
+	* @return array		Items that have been removed
+	*/
+	public function remove(phpbb_nestedset_item_interface $item);
+
+	/**
+	* Delete an item from the nested set (also deletes the rows form the table)
+	*
+	* Also deletes all subitems from the nested set
+	*
+	* @param phpbb_nestedset_item_interface	$item	The item to be deleted
+	* @return array		Items that have been deleted
+	*/
+	public function delete(phpbb_nestedset_item_interface $item);
+
+	/**
+	* Move an item by a given delta
+	*
+	* @param phpbb_nestedset_item_interface	$item	The item to be moved
+	* @param int	$delta	Number of steps to move this item, < 0 => down, > 0 => up
+	* @return bool True if the item was moved
+	*/
+	public function move(phpbb_nestedset_item_interface $item, $delta);
+
+	/**
+	* Move an item down by 1
+	*
+	* @param phpbb_nestedset_item_interface	$item	The item to be moved
+	* @return bool True if the item was moved
+	*/
+	public function move_down(phpbb_nestedset_item_interface $item);
+
+	/**
+	* Move an item up by 1
+	*
+	* @param phpbb_nestedset_item_interface	$item	The item to be moved
+	* @return bool True if the item was moved
+	*/
+	public function move_up(phpbb_nestedset_item_interface $item);
+
+	/**
+	* Moves all children of one item to another item
+	*
+	* @param phpbb_nestedset_item_interface	$current_parent		The current parent item
+	* @param phpbb_nestedset_item_interface	$new_parent			The new parent item
+	* @return bool True if any items where moved
+	*/
+	public function move_children(phpbb_nestedset_item_interface $current_parent, phpbb_nestedset_item_interface $new_parent);
+
+	/**
+	* Set the parent item
+	*
+	* @param phpbb_nestedset_item_interface	$item		The item to be moved
+	* @param phpbb_nestedset_item_interface	$new_parent	The new parent item
+	* @return bool True if the parent was set successfully
+	*/
+	public function set_parent(phpbb_nestedset_item_interface $item, phpbb_nestedset_item_interface $new_parent);
+
+	/**
+	* Get branch of the item
+	*
+	* This method can return all parents, children or both of the given item
+	*
+	* @param phpbb_nestedset_item_interface	$item		The item to get the branch from
+	* @param string		$type			One of all|parent|children
+	* @param bool		$order_desc		Order the items descending (most outer parent first)
+	* @param bool		$include_item	Should the given item be included in the list aswell
+	* @return array			Array of items (containing all columns from the item table)
+	*							ID => Item data
+	*/
+	public function get_branch_data(phpbb_nestedset_item_interface $item, $type, $order_desc, $include_item);
+
+	/**
+	* Get base information of parent items
+	*
+	* @param phpbb_nestedset_item_interface	$item		The item to get the parents from
+	* @return array			Array of items (containing basic columns from the item table)
+	*							ID => Item data
+	*/
+	public function get_parent_data(phpbb_nestedset_item_interface $item);
+
+	/**
+	* Recalculate Nested Sets
+	*
+	* @param int	$new_id		First left_id to be used (should start with 1)
+	* @param int	$parent_id	parent_id of the current set (default = 0)
+	* @param bool	$reset_ids	Should we reset all left_id/right_id on the first call?
+	* @return	int		$new_id		The next left_id/right_id that should be used
+	*/
+	public function recalculate_nested_set($new_id, $parent_id = 0, $reset_ids = false);
+}
diff --git a/phpBB/includes/nestedset/item/interface.php b/phpBB/includes/nestedset/item/interface.php
new file mode 100644
index 0000000000..18206d752e
--- /dev/null
+++ b/phpBB/includes/nestedset/item/interface.php
@@ -0,0 +1,61 @@
+<?php
+/**
+*
+* @package Nested Set
+* @copyright (c) 2013 phpBB Group
+* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
+*
+*/
+
+/**
+* @ignore
+*/
+if (!defined('IN_PHPBB'))
+{
+	exit;
+}
+
+interface phpbb_nestedset_item_interface
+{
+	/**
+	* Returns the ID of the item
+	*
+	* @return int
+	*/
+	public function get_item_id();
+
+	/**
+	* Returns the ID of the parent item
+	*
+	* @return int
+	*/
+	public function get_parent_id();
+
+	/**
+	* Returns a serialized or empty string with the data of the item's parents
+	*
+	* @return string
+	*/
+	public function get_item_parents_data();
+
+	/**
+	* Returns the left_id of the item
+	*
+	* @return int
+	*/
+	public function get_left_id();
+
+	/**
+	* Returns the right_id of the item
+	*
+	* @return int
+	*/
+	public function get_right_id();
+
+	/**
+	* Does the item have sub-items?
+	*
+	* @return bool
+	*/
+	public function has_children();
+}