Initial commit

Author: lazychaser

.gitignore

@@ -0,0 +1,4 @@
+/vendor
+composer.phar
+composer.lock
+.DS_Store

.travis.yml

@@ -0,0 +1,12 @@
+language: php
+
+php: 
+  - 5.3
+  - 5.4
+  - 5.5
+
+before_script:
+  - curl -s http://getcomposer.org/installer | php
+  - php composer.phar install --dev
+
+script: phpunit

README.markdown

@@ -0,0 +1,170 @@
+This is Laravel 4 package that simplifies creating, managing and retrieving trees
+in database. Using [Nested Set](http://en.wikipedia.org/wiki/Nested_set_model) 
+technique high performance descendants retrieval and path-to-node queries can be done.
+
+## Installation
+
+The package can be installed as Composer package, just include it into 
+`required` section of your `composer.json` file:
+
+    "required": {
+        "kalnoy/nestedset": "dev-master"
+    }
+
+## Basic usage
+
+Storing trees in database requires additional columns for the table, so these
+fields need to be included in table schema. We use `NestedSet::columns($table)`
+inside table schema creation function, like so:
+
+```php
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Kalnoy\Nestedset\NestedSet;
+
+class CreateCategoriesTable extends Migration {
+
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        Schema::create('categories', function(Blueprint $table) {
+            $table->increments('id');
+            $table->string('title');
+            $table->timestamps();
+
+            NestedSet::columns($table);
+        });
+
+        NestedSet::createRoot('categories', array(
+            'title' => 'Root',
+        ));
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down()
+    {
+        Schema::drop('categories');
+    }
+}
+```
+
+To simplify things root node is required. `NestedSet::createRoot` creates it for us.
+
+The next step is to create `Eloquent` model. Do it whatever way you like, but
+make shure that node is extended from `\Kalnoy\Nestedset\Node`, like here:
+
+```php
+<?php
+
+class Category extends \Kalnoy\Nestedset\Node {}
+```
+Now you can create nodes like so:
+
+```php
+$node = new Category(array('title' => 'TV\'s'));
+$node->appendTo(Category::root())->save();
+```
+
+the same thing can be done differently (to allow changing parent via mass assignment):
+
+```php
+$node->parent_id = $parent_id;
+$node->save();
+```
+
+You can insert the node right next to or before the other node:
+
+```php
+$srcNode = Category::find($src_id);
+$targetNode = Category::find($target_id);
+
+$srcNode->after($targetNode)->save();
+$srcNode->before($targetNode)->save();
+```
+
+Path to the node can be obtained in two ways:
+
+```php
+// Target node will not be included into result since it is already available
+$path = $node->path()->get();
+```
+
+or using the scope:
+
+```php
+// Target node will be included into result
+$path = Category::pathTo($nodeId)->get();
+```
+
+Descendant nodes can easily be gotten this way:
+
+```php
+$descendants = $node->descendants()->get();
+```
+
+Nodes can be provided with depth level if scope `withDepth` is applied:
+
+```php
+// Each node instance will recieve 'depth' attribute with depth level starting at
+// zero for the root node.
+$nodes = Category::withDepth()->get();
+```
+
+Query can be filtered out from the root node using scope `withoutRoot`.
+
+## Insertion, re-insertion and deletion of nodes
+
+Operations such as insertion and deletion of nodes imply several independent queries
+before node is actually saved. That is why if something goes wrong, the whole tree
+might be broken. To avoid such situations each call to `save()` must be enclosed 
+into transaction.
+
+Also, experimentally was noticed that using transaction drastically improves
+performance when tree gets update.
+
+## Advanced usage
+
+### Multiple node insertion
+
+_DO NOT MAKE MULTIPLE INSERTIONS DURING SINGLE HTTP REQUEST_
+
+Since when node is inserted or re-inserted tree is changed in database, nodes
+that are already loaded might also have changed and need to be refreshed. This
+doesn't happen automatically with exception of one scenario.
+
+Consider this example:
+
+```php
+$nodes = Category::whereIn('id', Input::get('selected_ids'))->get();
+$target = Category::find(Input::get('target_id'));
+
+foreach ($nodes as $node) {
+    $node->appendTo($target)->save();
+}
+```
+
+This is the example of situation when user picks up several nodes and moves them
+into new parent. When we call `appendTo` nothing is really changed but internal
+variables. Actual transformations are performed when `save` is called. When that
+happens, values of internal variables are definately changed for `$target` and
+might change for some nodes in `$nodes` list. But this changes happen in database
+and do not reflect into memory for loaded nodes. Calling `appendTo` with outdated 
+values brakes the tree.
+
+In this case only values of `$target` are crucial. The system always updates crucial
+attributes of parent of node being saved. Since `$target` becomes new parent for
+every node, the data of that node will always be up to date and this example will
+work just fine.
+
+_THIS IS THE ONLY CASE WHEN MULTIPLE NODES CAN BE INSERTED AND/OR RE-INSERTED 
+DURING SINGLE HTTP REQUEST WITHOUT REFRESHING DATA_

composer.json

@@ -0,0 +1,21 @@
+{
+    "name": "kalnoy/nestedset",
+    "description": "",
+    "authors": [
+        {
+            "name": "Aleksander Kalnoy",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": ">=5.3.0",
+        "illuminate/support": "4.0.x",
+        "illuminate/database": "4.0.x"
+    },
+    "autoload": {
+        "psr-0": {
+            "Kalnoy\\Nestedset": "src/"
+        }
+    },
+    "minimum-stability": "dev"
+}

phpunit.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit backupGlobals="false"
+         backupStaticAttributes="false"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false"
+         syntaxCheck="false"
+>
+    <testsuites>
+        <testsuite name="Package Test Suite">
+            <directory suffix=".php">./tests/</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/Kalnoy/Nestedset/Collection.php

@@ -0,0 +1,70 @@
+<?php namespace Kalnoy\Nestedset;
+
+use \Illuminate\Database\Eloquent\Collection as BaseCollection;
+
+class Collection extends BaseCollection {
+
+    /**
+     * Convert list of nodes to dictionary with specified key.
+     *
+     * If no key is specified then "parent_id" is used.
+     *
+     * @param string $key 
+     *
+     * @return  array
+     */
+    public function toDictionary($key = null)
+    {
+        if (empty($this->items)) {
+            return array();
+        }
+
+        if ($key === null) {
+            $key = $this->first()->getParentIdName();
+        }
+
+        $result = array();
+
+        foreach ($this->items as $item) {
+            $result[$item->$key][] = $item;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Build tree from node list.
+     *
+     * To succesfully build tree "id" and "parent_id" keys must present.
+     * 
+     * @param integer $rootNodeId
+     *
+     * @return  Collection
+     */
+    public function toTree($rootNodeId = null)
+    {
+        $dictionary = $this->toDictionary();
+        $result = new static();
+
+        // If root node is not specified we take first node's parent.
+        // This works since nodes are sorted by lft and first node has least depth.
+        if ($rootNodeId === null) {
+            $rootNodeId = $this->first()->getParentId();
+        }
+
+        $result->items = isset($dictionary[$rootNodeId]) ? $dictionary[$rootNodeId] : array();
+
+        if (empty($result->items)) {
+            return $result;
+        }
+
+        foreach ($this->items as $item) {
+            $key = $item->getKey();
+
+            $children = new BaseCollection(isset($dictionary[$key]) ? $dictionary[$key] : array());
+            $item->setRelation('children', $children);
+        }
+
+        return $result;
+    }
+}

src/Kalnoy/Nestedset/NestedSet.php

@@ -0,0 +1,63 @@
+<?php namespace Kalnoy\Nestedset;
+
+use \Illuminate\Database\Connection;
+use \Illuminate\Database\Schema\Blueprint;
+
+class NestedSet {
+
+    /**
+     * Add NestedSet columns to the table. Also create index and foreign key.
+     *
+     * @param   Blueprint  $table
+     *
+     * @return  void
+     */
+    static public function columns(Blueprint $table, $primaryKey = 'id')
+    {
+        $table->integer(Node::LFT);
+        $table->integer(Node::RGT);
+        $table->unsignedInteger(Node::PARENT_ID)->nullable();
+
+        $table->index([ Node::LFT, Node::RGT, Node::PARENT_ID ], 'nested_set_index');
+
+        $table
+            ->foreign(Node::PARENT_ID, 'nested_set_foreign')
+            ->references($primaryKey)
+            ->on($table->getTable())
+            ->onDelete('cascade');
+    }
+
+    /**
+     * Drop NestedSet columns.
+     *
+     * @param   Blueprint  $table
+     *
+     * @return  void
+     */
+    static public function dropColumns(Blueprint $table)
+    {
+        $table->dropForeign('nested_set_foreign');
+        $table->dropIndex('nested_set_index');
+        $table->dropColumn(Node::LFT, Node::RGT, Node::PARENT_ID);
+    }
+
+    /**
+     * Create root node.
+     *
+     * @param   string  $table
+     * @param   array   $extra
+     * @param   string  $connection
+     *
+     * @return  boolean
+     */
+    static function createRoot($table, array $extra = array(), $connection = null)
+    {
+        $extra = array_merge($extra, array(
+            Node::LFT => 1,
+            Node::RGT => 2,
+            Node::PARENT_ID => NULL,    
+        ));
+
+        return \DB::connection($connection)->table($table)->insert($extra);
+    }
+}