allows callers to show/hide json columns and attributes, adds tests for json hinting, updates readme

Author: Darryl Kuhn

README.md

@@ -13,6 +13,7 @@ Require this package in your `composer.json` file:
 ...then run `composer update` to download the package to your vendor directory.
 
 ## Usage
+### The Basics
 
 The feature is exposed through a trait called which allows you to define attributes on the model which are of the json datatype. When the model is read in it will parse the JSON document and set up getters and setters for each top level attribute making it easy to interact with the various attributes within the document. For example we could create a Photos model like this:
 
@@ -34,15 +35,48 @@ becomes this:
 $photo->key = value;
 ```
 Also when calling the toArray() method the attributes are moved to the top level and the 'json_attributes' column is hidden. This essentially hides away the fact that you're using the json datatype and makes it look like we're working with attributes directly.
- 
+
+### Relations
 You can also establish relationships on a model like this (only supported in PostgreSQL):
 ```php
 public function user()
 {
     return $this->hasOne( 'User', 'id', "json_data->>'user_id'" );
 }
 ```
-The one caveat is when you're setting an attribute not previously set already in the JSON document then no setter is created. For example if you defined a json column called "additional_details" which had a value of "{'foo':'bar'}" and wanted to set 'fizz' so you would need to call:
+
+### Structure Hinting
+Sometimes you may have an empty or partially populated record in which case the trait cannot automatically detect and create getters/setters, etc... When getting or setting an attribute not previously set in the JSON document you'll get an exception. You have two choices to deal with this. You can hint at the full structure as in the example below:
+```php
+class Photo extends Eloquent
+{
+    use Eloquent\Dialect\Json;
+    protected $jsonColumns = ['json_data'];
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->hintJsonStructure( 'json_data', '{"foo":null}' );
+    }
+}
+```
+Once you create a hint you will be able to make calls to get and set json attributes e.g. `$photo->foo = 'bar';` regardless of whether or not they are already defined in the underlying db record. Alternatly if you prefer not to hint structures then you may call `setJsonAttribute()`. For example if you defined a json column called "json_data" and wanted to set an attribute called 'fizz' so you could call:
+```php
+$referral->setJsonAttribute( 'json_data', 'fizz', 'buzz' );
+```
+### Showing/Hiding Attributes
+One of the aims of the project is to make json attributes "first class" citizens of the model. This means by default we add the attributes to the models appends array so that when you call `$model->toArray()` or `$model->toJson()` the attribute shows up as a part of the structure like a normal attribute. By default we also hide away the json column holding the underlying data. Both of these settings can be changed using the `showJsonColumns()` and `showJsonAttributes()` as shown below:
 ```php
-$referral->setJsonAttribute( 'additional_details', 'fizz', 'buzz' );
+class Photo extends Eloquent
+{
+    use Eloquent\Dialect\Json;
+    protected $jsonColumns = ['json_data'];
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->showJsonColumns(true);
+        $this->showJsonAttributes(false);
+    }
+}
 ```

src/Dialect/Json.php

@@ -3,7 +3,9 @@
 trait Json
 {
     /**
-     * List of known PSQL JSON operators
+     * List of known PSQL JSON operators. This is used when determining if
+     * a column reference matches that of a JSON pattern (e.g.
+     * test_column->>'value')
      *
      * @var array
      */
@@ -14,15 +16,39 @@ trait Json
         '#>>' ];
 
     /**
+     * Holds the map of attributes and the JSON colums they are stored in.
+     *
      * @var array
      */
     private $jsonAttributes = [];
 
     /**
+     * Holds a list of column names and the structure they *may* contain (e.g.
+     * ['json_column' => "{'foo':null}"]
+     *
      * @var array
      */
     private $hintedJsonAttributes = [];
 
+    /**
+     * By default this trait will hide the json columns when rendering the
+     * model using toArray() or toJson() only exposing the underlying JSON
+     * parameters as top level paremters on the model. Set this parameter to
+     * true if you want to change that behavior.
+     *
+     * @var boolean
+     */
+    private $showJsonColumns = false;
+
+    /**
+     * By default this trait will append the json attributes when rendering the
+     * model using toArray() or toJson(). Set this parameter to false if you
+     * want to change that behavior.
+     *
+     * @var boolean
+     */
+    private $showJsonAttributes = true;
+
     /**
      * Create a new model instance that is existing.
      * Overrides parent to set Json columns.
@@ -48,13 +74,17 @@ public function newFromBuilder($attributes = array(), $connection = null)
     public function inspectJsonColumns()
     {
         foreach ($this->jsonColumns as $col) {
-            $this->hidden[] = $col;
+            if ( !$this->showJsonColumns ) {
+                $this->hidden[] = $col;
+            }
             $obj = json_decode($this->$col);
 
             if (is_object($obj)) {
                 foreach ($obj as $key => $value) {
                     $this->flagJsonAttribute($key, $col);
-                    $this->appends[] = $key;
+                    if ( $this->showJsonAttributes ) {
+                        $this->appends[] = $key;
+                    }
                 }
             }
         }
@@ -70,7 +100,9 @@ public function inspectJsonColumns()
     public function addHintedAttributes()
     {
         foreach ($this->hintedJsonAttributes as $col => $structure) {
-            $this->hidden[] = $col;
+            if ( !$this->showJsonColumns ) {
+                $this->hidden[] = $col;
+            }
 
             if (json_decode($structure) === null) {
                 throw new InvalidJsonException;
@@ -81,7 +113,9 @@ public function addHintedAttributes()
             if (is_object($obj)) {
                 foreach ($obj as $key => $value) {
                     $this->flagJsonAttribute($key, $col);
-                    $this->appends[] = $key;
+                    if ( $this->showJsonAttributes ) {
+                        $this->appends[] = $key;
+                    }
                 }
             }
         }
@@ -156,9 +190,10 @@ public function getMutatedAttributes()
     /**
      * Check if the key is a known json attribute and return that value
      *
-     * @param  string  $key
-     * @param  mixed   $value
+     * @param  string $key
+     * @param  mixed  $value
      * @return mixed
+     * @throws  InvalidJsonException
      */
     protected function mutateAttribute($key, $value)
     {
@@ -176,15 +211,34 @@ protected function mutateAttribute($key, $value)
         }
 
         if (array_key_exists($key, $this->jsonAttributes) != false) {
+
+            // Get the content of the column associated with this JSON
+            // attribute and parse it into an object
             $value = $this->{$this->jsonAttributes[$key]};
-            if ( $value === null ) {
-                return null;
+            $obj = json_decode($this->{$this->jsonAttributes[$key]});
+
+            // Make sure we were able to parse the json. It's possible here
+            // that we've only hinted at an attribute and the column that will
+            // hold that attribute is actually null. This isn't really a parse
+            // error though the json_encode method will return null (just like)
+            // a parse error. To distenguish the two states see if the original
+            // value was null (indicating there was nothing there to parse in
+            // the first place)
+            if ( $value !== null && $obj === null ) {
+                throw new InvalidJsonException;
+            }
+
+            // Again it's possible the key will be in the jsonAttributes array
+            // (having been hinted) but not present on the actual record.
+            // Therefore test that the key is set before returning.
+            if ( isset($obj->$key) ) {
+                return $obj->$key;
             }
             else {
-                $obj = json_decode($this->{$this->jsonAttributes[$key]});
+                return null;
             }
-            return $obj->$key;
-        } elseif ($isJson) {
+        }
+        elseif ($isJson) {
             return null;
         }
 
@@ -234,4 +288,30 @@ public function setJsonAttribute($attribute, $key, $value)
         $this->{$attribute} = json_encode($obj);
         return;
     }
+
+    /**
+     * Allows you to specify if the actual JSON column housing the attributes
+     * should be shown on toArray() and toJson() calls. Set this value in the
+     * models constructor (to make sure it is set before newFromBuilder() is
+     * called). This is false by default
+     *
+     * @param  boolean $show
+     * @return boolean
+     */
+    public function showJsonColumns( $show ) {
+        return $this->showJsonColumns = $show;
+    }
+
+    /**
+     * Allows you to specify if the attributes within various json columns
+     * should be shown on toArray() and toJson() calls. Set this value in the
+     * models constructor (to make sure it is set before newFromBuilder() is
+     * called). This is true by default
+     *
+     * @param  boolean show
+     * @return boolean
+     */
+    public function showJsonAttributes( $show ) {
+        return $this->showJsonAttributes = $show;
+    }
 }