README

    __                                __    _______ ____  _   __
   / /   ____ __________ __   _____  / /   / / ___// __ \/ | / /
  / /   / __ `/ ___/ __ `/ | / / _ \/ /_  / /\__ \/ / / /  |/ / 
 / /___/ /_/ / /  / /_/ /| |/ /  __/ / /_/ /___/ / /_/ / /|  /  
/_____/\__,_/_/   \__,_/ |___/\___/_/\____//____/\____/_/ |_/

Adds support for the JSON datatype column for models via an object based interface.

This package has been developed by H&H|Digital, an Australian botique developer. Visit us at hnh.digital.

Install

$ composer require hnhdigital-os/laravel-model-json ~1.0

Usage

Basic

The feature is exposed through a trait that allows you to define columns that contain JSON data. When the model is created, it generates methods using the specified column names. You can then get and set the attributes directly.

use Bluora\LaravelModelJson\JsonColumnTrait;

class User extends Model
{
    use JsonColumnTrait;

    protected $json_columns = [
        'settings'
    ];
}

The JSON column values can then be retrieved or set via an object property.

Let's say we have an array of data stored in the settings JSON column:

['showProfilePicture' => true, 'options' => ['option1' => 'red']];

Getting these values is as simple as:

echo $user->settings()->showProfilePicture."\n";
echo $user->settings()->options['option1'];

Would output:

1
red

You can update any variable or add a new one:

$user->settings()->options['option2'] = 1;
$user->save();

And would update the JSON object with the following array:

['showProfilePicture' => true, 'options' => ['option1' => 'red', 'option2' => 1]];

Calling getDirty with true will provide changes using dot notation.

print_r($user->getDirty(true));

Would output:

array(
    'settings' => "{"showProfilePicture":true,"options":{"option1":"red","option2":1}}",
    'settings.options' => array('option2' => 1)
)

NOTE

If you use findOrNew, firstOrNew, firstOrCreate, or the updateOrCreate method, you should run the inspectJson method before using any JSON columns as the newFromBuilder method (which we override) is not called on new model objects.

$model = Model::firstOrNew(['name' => 'example']);
$model->inspectJson();

Defaults

You can define default values for a json attribute by using the $json_defaults property on the model.

You specify the attribute name and default value, if the name does not exist, it will be added at the creation of the object.

protected $json_defaults = [
    'settings' => ['showProfilePicture' => 0]
];

Saving changes

When a save event has been called, the trait sets the original attribute value with the latest JSON encoded value.

If you have used defaults, you can stop these from being saved to the database by setting the option no_saving_default_values to true for the specific json column

protected $json_options = [
    'settings' => ['no_saving_default_values' => true]
];

bluora / laravel-model-json

Maintainers

Details