From c15f8cf2a828bd65dde293212f027082c4c40193 Mon Sep 17 00:00:00 2001
From: Roman Kinyakin <1@grep.su>
Date: Thu, 14 May 2015 11:49:46 +0600
Subject: [PATCH] Fillable trait documentation

---
 README.md        | 60 ++++++++++++++++++++++++++++++++++++++++++++++--
 src/Fillable.php |  7 +++---
 2 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index bb57106..9fc6ea2 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-## Attributable trait
+## Attributable
 
 [![Build Status](https://travis-ci.org/rkgrep/attributable.svg)](https://travis-ci.org/rkgrep/attributable)
 [![Latest Stable Version](https://poser.pugx.org/rkgrep/attributable/v/stable.svg)](https://packagist.org/packages/rkgrep/attributable)
@@ -7,7 +7,7 @@
 
 > **Note:** Original idea by Taylor Otwell in [Laravel Framework](https://github.com/laravel/framework).
 
-The trait is used to provide fast and elegant way to work with objects.
+The package includes traits which allow fluent and elegant way to work with internal object property arrays.
 
 ## Installation
 
@@ -26,8 +26,20 @@ class Foo {
 }
 ````
 
+````php
+class Bar {
+    
+    use rkgrep\Fillable;
+    
+}
+````
+
 ## Usage
 
+### Attributable trait
+
+`Attributable` provides different access and assignment ways.
+
 Assign internal variables via property or method call
 
 ````php
@@ -68,6 +80,48 @@ Chain methods for fast assignment
 $user->first_name('John')->last_name('Doe')->admin();
 ````
 
+### Fillable trait
+
+`Fillable` provides chaining assignment of variables or groups of variables.
+
+Mass assign atributes with `fill` method
+
+````php
+$user->fill(['name' => 'Admin', 'email' => 'admin@example.com']);
+````
+
+Overwrite or reassign control via second parameter
+
+````php
+$user->fill(['name' => 'John Doe']); // Name changed, email remains untouched
+$user->fill(['email' => 'other@example.com'], false); // Disabled merging - old values are dropped
+````
+
+Fill specific properties with `with` method
+
+````php
+$user->with('password', md5('password'));
+````
+
+Prevent overriding with third parameter
+
+````php
+$user->with('password', '', false); // Password remains untouched
+````
+
+Assign multiple variables
+
+````php
+$user->with(['friends' => ['Mike', 'Dave'], 'girlfriend' => 'Jane']);
+$user->with(['siblings' => [], 'girlfriend' => 'Mary'], null, false); // Overriding disabled - only siblings are touched
+````
+
+Chain method calls
+
+````php
+$post->fill(['title' => 'Lorem Ipsum'])->with('views', 5)->with('likes', 3);
+````
+
 ## Interfaces
 
 Any class with `Attributable` trait applied implements `ArrayAccess` and `JsonSerializable`.
@@ -75,7 +129,9 @@ If you use *illuminate/support* package you can also apply `Arrayable` and `Json
 
 ````php
 class Bar implements ArrayAccess, JsonSerializable, Arrayable, Jsonable {
+
     use rkgrep\Attributable;
+
 }
 
 $bar = new Bar();
diff --git a/src/Fillable.php b/src/Fillable.php
index 33548f0..ac90b8e 100644
--- a/src/Fillable.php
+++ b/src/Fillable.php
@@ -37,12 +37,13 @@ public function with($key, $value = null, $overwrite = true)
     /**
      * Fill container with values
      *
-     * @param  array $data
+     * @param  array   $data
+     * @param  boolean $merge
      * @return $this
      */
-    public function fill(array $data)
+    public function fill(array $data, $merge = true)
     {
-        $this->attributes = array_merge($this->attributes, $data);
+        $this->attributes = ($merge) ? array_merge($this->attributes, $data) : $data;
         return $this;
     }
 }
\ No newline at end of file