DB_NestedSet

API to build and query nested sets

DB_NestedSet let's you create trees with infinite depth inside a relational database. The package provides a way to o create/update/delete nodes o query nodes, trees and subtrees o copy (clone) nodes, trees and subtrees o move nodes, trees and subtrees o call event handlers on specific events like on node deletion o output the tree with - PEAR::HTML_TreeMenu - TigraMenu (http://www.softcomplex.com/products/tigra_menu/) o It also features caching of SQL queries using PEAR::Cache datenpunk Daniel Khan dk@webcluster.at lead jrust Jason Rust jrust@rustyparts.com developer 1.3 2003-10-07 PHP License beta This release includes many internal changes and some (long demanded) feature additions. The API and database structure should be fully backward compatible. Please test this release as much as possible, so that any remaining issues can be uncovered and resolved prior to the final release. o Notes: If you want to use new features like preorder sorting you will have to convert the tree to meet the new db model. See docs/migrateDB.txt on how to migrate your existing tree. o Fixes: * MDB support is back again. * Fixed a problem with some move operations where the moving tree gets changed during the move operation. * Many small internal fixes. o New features: * Added a method setSortMode($mode) where $mode is NESE_SORT_LEVEL or NESE_SORT_PREORDER. This will change the way the query methods return the tree. NESE_SORT_LEVEL is the default. NESE_SORT_PREORDER returns the tree preorder sorted. This sorting method was often demanded as it's the way one would usually expect the tree to be returned. Preorder sorting will also work with the property $secondarySort. So it's possible to get the siblings of one level sorted alphabetically by name. Note that you will have to switch back to NESE_SORT_LEVEL if you want to display a tree with the output drivers. * Added method getParent() to get the immediate parent of a node * Added method getSiblings() to get all siblings of a node + the node itself * Added method createLeftNode() to create a node before a node given by it's node id. * Added method apiVersion() which obviously returns the current API version * Added convertTreeModel() to convert a tree into the new tree model * Added magic parent db field. If a column with the field mapping 'parent' is present the parent id of a node is stored inside this column. This doesn't exactly meet the nested sets theory and will only be used by some methods like getParent(). It's recommended to use this column for new installations or converted trees. * Now values passed to creation methods are verfified so that a script can't set params like the parent id by itself * Added listbox_toHTML() and tree_toHTML() methods to the TreeMenu output driver. Thanks to Emanuel Zueger for this additions. * Added regression tests for all public methods and common options The regression test setup isn't very userfriendly for now. The db schema can be found under docs and you will have to customize tests/UnitTest.php to set your database connection params. * The main class now uses the array representation of the tree for internal operations. This should gain some performance. o Notes on next major version (1.3): * The API will change. * The class won't return objects anymore. It will act as if $keepAsArray is set to true when calling the query methods. It's a good idea to switch to set this param to be mostly compatible. * Callback handlers will be removed - I don't even know if someone uses them. Please mail me at dk@webcluster.at if you really see a use. -- To be continued -- 1.2.4 2003-08-13 stable o Fixed a problem in re-sorting after node deletion o Added an example for building a JavaScript tree with TreeMenu 1.2.3 2003-07-16 stable o Fixes a typo in _addSQL() Thanks to Rense Klinkenberg for sending patch 1.2.2 2003-07-15 stable This release fixes some bugs which occured since 1.2.1 We will now move towards 2.0 which will include big improvements but also some BC breaks. FIXES o Fixed a bug which leads to wrong results when copying nodes o Fixed a node ordering bug in createRightNode (Thanks to Stefan Wimmer) o Fixed bug that had crept in so that $aliasFields was not working o Doc and style fixes 1.2.1 2003-05-25 stable - NEW FEATURES o Now $NeSe->setAttr() allows a PEAR function cache object to be passed using $NeSe->setAttr(array('cache'=>$cache_object)); if this object is set, the class will use it to cache database queries. It will also flush this cache if the structure changes. o All tree query methods now support an additional array named $addSQL. This can be used to pass additional params to a query. Means: You may now use joins to other tables. - FIXES o createRightNode() returned the node object instead of the new node id, which caused problems whith some internal method calls. o TreeMenu and TigraMenu output drivers contained a bug which made them not create the whole tree under certain circumstances Thanks to Alain Petignat for reporting this o Some minor E_ALL fixes (The package shouldn't produce notices/warnings with E_ALL set) o Added TigraMenu.php to the package which was missing in the last release 1.2pl1 2003-05-08 stable - Fixed a bug which leads to the deletion of a node or subtree if a node is moved into _itself_. Thanks to Christian Reininger for catching this! - Now a proper PEAR::Error object is returned in case of recursion instead of returning false. 1.2 2003-05-05 stable The core package is now stable. You should be able to manipulate a nested set without problems. The output driver development will always be in progress and there may always be drivers in beta state. This package introduces an output driver for TigraMenu (http://www.softcomplex.com/products/tigra_menu/) and examples on using the output drivers. * Fixed bug in triggerEvent() which produced an error on node move (Daniel Khan) * Added isParent() which provides a simple way to query if a given node is parent of another given node. (Daniel Khan) * Added a variable to pickNode() which can be used to get a node by another value than id (Daniel Khan) * TreeMenu: Fixed bug where two sub nodes that both have children were not being processed correctly (Jason Rust) * TreeMenu: Took off example usage since there is now an example page in docs/ (Jason Rust) * TigraMenu: Initial import of TigraMenu output driver 1.1-beta 2003-04-29 beta - Added a unified API to access other output drivers - Added a output driver for HTML_TreeMenu (Jason Rust) - Added a variable '$idfield' to pickNode() which can be used to get a node by another value than id (Daniel Khan) - Made getChildren() consistent with how the other methods work in terms of the secondarySort property (Jason Rust) - Added new attribute: secondarySort. Normally it is the order field, but can be set to another field in the table such as name so that the tree can be displayed alphabetically. (Jason Rust) - Improved the error handling so that nasty fatal errors no longer occur if invalid ids are specified (Jason Rust) - Now using the NESE_MOVE_* constants instead of AF, BE, and SUB (Jason Rust) - Added vim folds (Jason Rust) - Several style fixes to be compliant with PEAR style (Jason Rust) - Several E_ALL fixes (Jason Rust) - Avoid repetitive setting of variables by using sprintf to form the SQL queries in many of the _doget* methods (Jason Rust) - db->quote() is now used to quote strings to be compliant with other databases (Jason Rust) - Added new property: sequence_table so that it can be configurable (Jason Rust) - Added new method: setDbOption in order to be able to set database options (Jason Rust) - Added new method to NestedSet_Node: getData() to obtain the data from the node in an array (Jason Rust) - NestedSet_Node no longer extends PEAR since it doesn't need to (Jason Rust) - Fixed a bug for when moving a node within its level (Jason Rust) - Locking does not produce DB "database not set" errors any longer since the database destructor calls the parent destructor first (Jason Rust) - Fixed a bug in _dogetParents() which made it return also return the parent's sibblings (Daniel Khan)