From 2b619534ff902b381c5423aee63b6f25b8cd884d Mon Sep 17 00:00:00 2001
From: Jan Iwanow <iwanow.jan@gmail.com>
Date: Sat, 14 Feb 2015 14:32:35 +1000
Subject: [PATCH] added flag to addChild() and addSibling() to be able to
 return the child or the sibling, updated the docs

---
 README.md                                          |  6 ++++++
 docs/usage.rst                                     |  6 ++++++
 .../ClosureTable/Contracts/EntityInterface.php     | 10 ++++++----
 src/Franzose/ClosureTable/Models/Entity.php        | 14 ++++++++------
 4 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 1631d97..58dafaf 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,9 @@ $page->addChild($newChild);
 //you can set child position
 $page->addChild($newChild, 5);
 
+//you can get the child
+$child = $page->addChild($newChild, null, true);
+
 $page->addChildren([$newChild, $newChild2]);
 
 $page->getChildAt(5);
@@ -151,6 +154,9 @@ $sibligns = $page->getSiblingsRange(0, 2);
 $page->addSibling(new Page);
 $page->addSibling(new Page, 3); //third position
 
+//add and get the sibling
+$sibling = $page->addSibling(new Page, null, true);
+
 $page->addSiblings([new Page, new Page]);
 $page->addSiblings([new Page, new Page], 5); //insert from fifth position
 ```
diff --git a/docs/usage.rst b/docs/usage.rst
index abd6a09..e4b1127 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -54,6 +54,9 @@ Direct descendants (children)
 	//you can set child position
 	$page->addChild($newChild, 5);
 
+	//you can get the child
+	$child = $page->addChild($newChild, null, true);
+
 	$page->addChildren([$newChild, $newChild2]);
 
 	$page->getChildAt(5);
@@ -107,6 +110,9 @@ Siblings
 	$page->addSibling(new Page);
 	$page->addSibling(new Page, 3); //third position
 
+	//add and get the sibling
+	$sibling = $page->addSibling(new Page, null, true);
+
 	$page->addSiblings([new Page, new Page]);
 	$page->addSiblings([new Page, new Page], 5); //insert from fifth position
 
diff --git a/src/Franzose/ClosureTable/Contracts/EntityInterface.php b/src/Franzose/ClosureTable/Contracts/EntityInterface.php
index c2317c4..423e014 100644
--- a/src/Franzose/ClosureTable/Contracts/EntityInterface.php
+++ b/src/Franzose/ClosureTable/Contracts/EntityInterface.php
@@ -224,9 +224,10 @@ public function getLastChild(array $columns = ['*']);
      *
      * @param EntityInterface $child
      * @param int $position
-     * @return $this
+     * @param bool $returnChild
+     * @return EntityInterface
      */
-    public function addChild(EntityInterface $child, $position = null);
+    public function addChild(EntityInterface $child, $position = null, $returnChild = false);
 
     /**
      * Appends multiple children to the model.
@@ -387,9 +388,10 @@ public function getSiblingsRange($from, $to = null, array $columns = ['*']);
      *
      * @param EntityInterface $sibling
      * @param int|null $position
-     * @return $this
+     * @param bool $returnSibling
+     * @return EntityInterface
      */
-    public function addSibling(EntityInterface $sibling, $position = null);
+    public function addSibling(EntityInterface $sibling, $position = null, $returnSibling = false);
 
     /**
      * Appends multiple siblings within the current depth.
diff --git a/src/Franzose/ClosureTable/Models/Entity.php b/src/Franzose/ClosureTable/Models/Entity.php
index 3d3e0fa..033514a 100644
--- a/src/Franzose/ClosureTable/Models/Entity.php
+++ b/src/Franzose/ClosureTable/Models/Entity.php
@@ -686,9 +686,10 @@ protected function getLastChildPosition()
      *
      * @param EntityInterface $child
      * @param int $position
-     * @return $this
+     * @param bool $returnChild
+     * @return EntityInterface
      */
-    public function addChild(EntityInterface $child, $position = null)
+    public function addChild(EntityInterface $child, $position = null, $returnChild = false)
     {
         if ($this->exists)
         {
@@ -700,7 +701,7 @@ public function addChild(EntityInterface $child, $position = null)
             $child->moveTo($position, $this);
         }
 
-        return $this;
+        return ($returnChild === true ? $child : $this);
     }
 
     /**
@@ -1024,9 +1025,10 @@ public function getSiblingsRange($from, $to = null, array $columns = ['*'])
      *
      * @param EntityInterface $sibling
      * @param int|null $position
-     * @return $this
+     * @param bool $returnSibling
+     * @return EntityInterface
      */
-    public function addSibling(EntityInterface $sibling, $position = null)
+    public function addSibling(EntityInterface $sibling, $position = null, $returnSibling = false)
     {
         if ($this->exists)
         {
@@ -1038,7 +1040,7 @@ public function addSibling(EntityInterface $sibling, $position = null)
             $sibling->moveTo($position, $this->parent_id);
         }
 
-        return $this;
+        return ($returnSibling === true ? $sibling : $this);
     }
 
     /**