root/plugins/sfPropelActAsNestedSetBehaviorPlugin/README

= sfPropelActAsNestedSetBehaviorPlugin plugin =

The `sfPropelActAsNestedSetBehaviorPlugin` is a symfony plugin that provides nested set capabilities to Propel objects.

Nested sets (aka modified preorder tree traversal) is a very efficient way (in terms of performances) to browse and edit a tree like structure in an RDBMS.

You can read [http://dev.mysql.com/tech-resources/articles/hierarchical-data.html a good introduction to nested sets] on MySQL developers' zone.

== Features ==

 * Fully unit tested
 * Possibility to store multiple trees in the same table
 * Atomic operations
 * Also maintains adjacency list properties, making your classes compatible with code based on this tree traversal methodology
 
== Limitations ==

As of now, the plugin is known to work with MySQL and PostgreSQL (in trunk). Other RDBMS may work but without any guaranty.
Patches are welcome, of course :)

== Installation ==

  * Install the plugin
  
    {{{
      symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsNestedSetBehaviorPlugin
    }}}

  * Add new fields to your schema.xml
    
   {{{
   #!xml
    <column name="tree_left"   type="INTEGER"   required="true" /> 
    <column name="tree_right"  type="INTEGER"   required="true" /> 
    <column name="tree_parent" type="INTEGER"   required="true" /> 
    <column name="scope"       type="INTEGER"   required="true" />
   }}}

  `scope` and `tree_parent` columns can be of any type. 

  * Enable Propel behavior support in `propel.ini`:

    {{{
      propel.builder.AddBehaviors = true
    }}}
  
    If you have to enable the behavior support, rebuild your model:

    {{{
      symfony propel-build-model
    }}}

  * Enable the behavior for one of your Propel model:

    {{{
    #!php
    <?php
      // lib/model/ForumPost.php
      class ForumPost
      {
      }

      $columns_map = array('left'   => ForumPostPeer::TREE_LEFT,
                           'right'  => ForumPostPeer::TREE_RIGHT,
                           'parent' => ForumPostPeer::TREE_PARENT,
                           'scope'  => ForumPostPeer::TOPIC_ID);
 
      sfPropelBehavior::add('ForumPost', array('actasnestedset' => array('columns' => $columns_map)));
    }}}

  The ''column map'' is used by the behavior to know which columns hold information it needs :
  
    * left : Model column holding nested set left value for a row
    * right : Model column holding nested set right value for a row
    * parent : Model column holding row's parent id (this is necessary because we use adjacency list tree traversal for some methods)
    * scope : Model column holding row's scope id. The scope is used to differenciate trees stored in the same table

== Usage ==

=== Simple tree creation ===

{{{
#!php
<?php
  $root = new ForumPost();
  $root->makeRoot();
  $root->save();

  $p1 = new ForumPost();
  $p1->insertAsFirstChildOf($root);
  $p1->save();

  $p2 = new ForumPost();
  $p2->insertAsFirstChildOf($p1);
  $p2->save();

  /*
   * Resulting tree :
   *
   * ROOT
   * |- P1
   *    |- P2
   */
}}}

=== Multiple trees in a single table ===

{{{
#!php
<?php
  $root1 = new ForumPost();
  $root1->makeRoot();
  $root1->setTopicId(1);
  $root1->save();

  $root2 = new ForumPost();
  $root2->makeRoot();
  $root2->setTopicId(2);
  $root2->save();

  $p1 = new ForumPost();
  $p1->insertAsFirstChildOf($root1);
  $p1->save();

  $p2 = new ForumPost();
  $p2->insertAsFirstChildOf($root2);
  $p2->save();

  /*
   * Resulting trees :
   *
   * ROOT1
   * |- P1
   * 
   * ROOT2
   * |- P2
   */
}}}

=== Lame threaded forum posts list example ===

{{{
#!php
  <?php $root = ForumPostPeer::retrieveByPk(rootnodepk); ?>
  <ul>
    <?php echo $root->getTitle() ?>

    <?php foreach ($root->getDescendants() as $post): ?>

       <li style="padding-left: <?php echo $post->getLevel() ?>em;">
            <?php echo $post->getTitle() ?>
       </li>

    <?php endforeach; ?>
  </ul>
}}}

=== Using nested sets and sfPropelPager ===

{{{
#!php
<?php
  // Decide which posts to fetch
  $c = new Criteria();
  $c->add(ForumPostPeer::TOPIC_ID, $topic_id);
  $c->addAscendingOrderByColumn(ForumPostPeer::TREE_LEFT); // ForumPostPeer::TREE_LEFT is the column holding nested set's left value
    
  // Create pager
  $pager = new sfPropelPager('ForumPost', 10);
  $pager->setCriteria($c);
  $pager->setPage($this->getRequestParameter('page', 1));
  $pager->init();
}}}

== Public API ==

Enabling the behaviors adds the following method to the Propel objects :

=== Insertion methods ===

 * `void insertAsFirstChildOf(BaseObject $dest_node)` : Inserts node as first child of given node.
 * `void insertAsLastChildOf(BaseObject $dest_node)` : Inserts node as last child of given node.
 * `void insertAsNextSiblingOf(BaseObject $dest_node)` : Inserts node as next sibling of given node.
 * `void insertAsPrevSiblingOf(BaseObject $dest_node)` : Inserts node as previous sibling of given node.
 * `void insertAsParentOf(BaseObject $dest_node)` : Inserts node as parent of given node

=== Informational methods ===

 * `bool hasChildren()` : Returns true if given node as one or several children.
 * `bool isRoot()` : Returns true if given node is a root node.
 * `bool hasParent()` : Returns true if given node has a parent node.
 * `bool hasNextSibling()` : Returns true if given node has a next sibling.
 * `bool hasPrevSibling()` : Returns true if given node has a previous sibling.
 * `bool isLeaf()` : Returns true if given node does not have children.
 * `bool isChildOf(BaseObject $node)` : Returns true if given node is parent of node.
 * `bool isDescendantOf(BaseObject $node)` : Returns true if given node is descendant of node.
 * `integer getNumberOfChildren()` : Returns given node number of direct children.
 * `integer getNumberOfDescendants()` : Returns given node number of descendants (n level).
 * `integer getLevel()` : Returns given node level.

=== Node retrieval methods ===

 * `BaseObject|null getParent($peer_method = 'retrieveByPk')` : Returns node parent or null if node does not have a parent.
 * `array getChildren($peer_method = 'doSelect')` : Returns given node direct children.
 * `array getDescendants($peer_method = 'doSelect')` : Returns given node descendants (n level).
 * `BaseObject retrieveNextSibling()` : Returns given node next sibling.
 * `BaseObject retrievePrevSibling()` : Returns given node previous sibling.
 * `BaseObject retrieveFirstChild()` : Returns given node first child.
 * `BaseObject retrieveLastChild()` : Returns given node last child.
 * `BaseObject retrieveParent($peer_method = 'doSelectOne')` : Returns given node parent.
 * `array retrieveSiblings()` : Returns node siblings.
 * `array getPath($peer_method = 'doSelectOne')` : Returns path to a specific node as an array, useful to create breadcrumbs.

=== Tree modification methods ===

 * `void moveToFirstChildOf(BaseObject $dest_node)` : Moves node to first child of given node.
 * `void moveToLastChildOf(BaseObject $dest_node)` : Moves node to last child of given node.
 * `void moveToNextSiblingOf(BaseObject $dest_node)` : Moves node to next sibling of given node.
 * `void moveToPrevSiblingOf(BaseObject $dest_node)` : Moves node to previous sibling of given node.
 * `void deleteChildren()` : Deletes node direct children
 * `void deleteDescendants()` : Deletes node descendants (n level)

=== Helper methods ===

 * `void makeRoot()` : Sets node properties to make it a root node.
 * `BaseObject reload()` : Returns an up to date version of node
 * `bool isEqualTo(BaseObject $node)` : Returns true if given node is equivalent to node.

== Roadmap ==

=== 0.10.0 ===

==== Features ====

 * add support for symfony's i18n capabilities
 * add criteria option to more methods
 * add `$peer_method` as an optional parameter to `getParent()` and `getPath()` 
 * add multiple connections support
 * add transactional support
 * get rid of mysql dependency : rewrite queries "criteria-like" or implement adapter.
 * add a method to copy a whole tree to another scope
 * make it possible to delete a root node that has children
 
== Changelog ==

=== 2007-07-23 | 0.9.1-beta ===

==== Bugfixes ====

 * fixed `getLevel()` cache (gordon franke)
 * fixed scope handling : scope can be any type of data (Jorn.Wagner)
 * `retrieveFirstChild()` and `retrieveLastChild()` missing references to scope node (Olivier.Mansour)
 * fixed postgresql compatibility (Maciej.Filipiak & Krasimir.Angelov)
 * added a note about supported RDBMS (tristan)
 * made roadmap clearer (tristan)
 * removed useless Propel::getConnection (Eric.Fredj)
 * fixed scope handling in `deleteDescendants()` (Piers.Warmers)
 * fixed new `getDescendants()` implementation node level caching (tristan)

==== Enhancements ====

 * added new `isDescendantOf()` method (Piers.Warmers)
 * implemented faster getPath() method (francois)
 * implemented faster `getDescendants()` (Jon.Collins)

=== 2007-05-24 | 0.9.0-beta ===

 * Licence change : MIT -> LGPL
 * Please welcome a new maintainer : Gordan Franke :)
 * tree "dumper" utility method :  `sfPropelActAsNestedSetBehaviorUtils::dumpTree()`
 * add optional select method for getPath|getParent|retrieveParent (gordon)

=== 2007-04-18 | 0.8.2-beta ===

 * added `getParent()` method (olivier mansour)
 * added `getLevel()` unit tests
 * implemented caching of level in collection retrieval methods : `getDescendants()`, `getChildren()`, `retrieveSiblings()`
 * defined plugin roadmap

=== 2007-03-22 | 0.8.1-beta ===

 * fixed #1480 : non-abstracted column name (paul markovitch)
 * fixed bug in `getStubFromPeer()`
 * `makeRoot()` should accept non new objects (peter van garderen)
 * `getDescendants()` should not try to get descendants if node is a leaf (peter van garderen)
 * updated unit tests
 * enabled syntax highlighting in README

=== 2007-02-19 | 0.8.0-beta ===

Implemented more methods (+ unit tests) :

 * `insertAsParentOf`
 * `retrieveSiblings`
 * `isEqualTo`
 * `isChildOf`

Enhanced internal API

=== 2007-02-19 | 0.7.0-beta ===

Implemented missing methods (+ unit tests) :
 
 * `moveToPrevSiblingOf`
 * `moveToNextSiblingOf`
 * `deleteChildren`
 * `deleteDescendants`

=== 2007-02-19 | 0.6.2-beta ===

Fixed a bug due to wrong usage of `rtrim`. (Thanks to Krešo Kunjas)

=== 2007-02-15 | 0.6.1-beta ===

Fixed minor bug in `getPath()`

=== 2007-02-15 | 0.6.0-beta ===

Implemented missing node retrieval methods : 

 * `retrieveFirstChild`
 * `retrieveLastChild`
 * `retrieveParent`
 * `getPath`
 
Updated docs and unit tests accordingly

=== 2007-02-14 | 0.5.1-beta ===

Pear package missed plugin's config.php file.

=== 2007-02-14 | 0.5.0-beta ===

Initial public release. The behavior is stable and fully unit-tested, but the API is not yet complete. Missing methods :

 * `retrieveFirstChild`
 * `retrieveLastChild`
 * `moveToPrevSiblingOf`
 * `moveToNextSiblingOf`
 * `deleteChildren`
 * `deleteTree`
 * `getPath`

== Maintainers ==
 
Tristan Rivoallan and Gordon Franke.

== Contributors ==

Krasimir Angelov, Jon Collins, Maciej Filipiak, Eric Fredj, Peter van Garderen, Olivier Mansour, Paul Markovitch,
Krešo Kunjas, Piers Warmers, Francois Zaninotto.

Plugin's code is based on work from [http://propel.phpdb.org/trac/ticket/312 Heltem] 
and [http://www.symfony-project.com/forum/index.php/m/20657/ Joe Simms]. 

Thanks to all of you !