Laravel Model Settings

Model Settings for your Laravel app

Model Settings for your Laravel app

The package requires PHP 7.3+ and follows the FIG standards PSR-1, PSR-2, PSR-4 and PSR-12 to ensure a high level of interoperability between shared PHP.

Bug reports, feature requests, and pull requests can be submitted by following our Contribution Guide.

#Table of contents

• Installation
• Updating your Eloquent Models
  • Option 1 - HasSettingsField trait
  • Option 2 - HasSettingsTable trait
  • Option 3 - HasSettingsRedis trait
• Default Settings
• Usage
  • Check if the settings for the entity is empty (exist)
  • Check settings (exist)
  • Get all model's settings
  • Get a specific setting
  • Add / Update setting
  • Check if the model has a specific setting
  • Remove a setting from a model
  • Persistence
  • Using another method name other than settings()
  • Validation system for settings data
• Changelog
• Contributing
• License

#Installation

$ composer require glorand/laravel-model-settings

{
    "require": {
        "glorand/laravel-model-settings": "^4.0"
    }
}

#Env (config) variables (.env file)

Default name for the settings field - when you use the HasSettingsField

MODEL_SETTINGS_FIELD_NAME=settings

Default name for the settings table - when you use the HasSettingsTable

MODEL_SETTINGS_TABLE_NAME=model_settings

#Updating your Eloquent Models

Your models should use the HasSettingsField or HasSettingsTable trait.

#Option 1 - HasSettingsField trait

Run the php artisan model-settings:model-settings-field in order to create a migration file for a table.
This command will create a json field (default name settings, from config) for the mentioned table.

You can choose another than default, in this case you have to specify it in you model.

public $settingsFieldName = 'user_settings';

Complete example:

use Glorand\Model\Settings\Traits\HasSettingsField;
 
class User extends Model
{
    use HasSettingsField;
 
    //define only if you select a different name from the default
    public $settingsFieldName = 'user_settings';
 
    //define only if the model overrides the default connection
    protected $connection = 'mysql';
 
}

#Option 2 - HasSettingsTable trait

Run before the command php artisan model-settings:model-settings-table.
The command will copy for you the migration class to create the table where the setting values will be stored.
The default name of the table is model_settings; change the config or env value MODEL_SETTINGS_TABLE_NAME if you want to rewrite the default name (before you run the command!)

use Glorand\Model\Settings\Traits\HasSettingsTable;
 
class User extends Model
{
    use HasSettingsTable;
}

#Option 3 - HasSettingsRedis trait

use Glorand\Model\Settings\Traits\HasSettingsRedis;
 
class User extends Model
{
    use HasSettingsRedis;
}

#Default settings

You can set default configs for a table in model_settings.php config file

return [
    // start other config options
 
    // end other config options
 
    // defaultConfigs
    'defaultSettings' => [
        'users' => [
            'key_1' => 'val_1',
        ]
    ]
];

Or in your model itself:

use Glorand\Model\Settings\Traits\HasSettingsTable;
 
class User extends Model
{
    public $defaultSettings = [
        'key_1' => 'val_1',
    ];
}

Please note that if you define settings in the model, the settings from configs will have no effect, they will just be ignored.

#Usage

$user = App\User::first();

#Check if the settings for the entity is empty

$user->settings()->empty();

#Check settings (exist)

$user->settings()->exist();

#Get all model's settings

$user->settings()->all();
$user->settings()->get();

#Get a specific setting

$user->settings()->get('some.setting');
$user->settings()->get('some.setting', 'default value');
//multiple
$user->settings()->getMultiple(
    [
        'some.setting_1',
        'some.setting_2',
    ],
    'default value'
);

#Add / Update setting

$user->settings()->apply((array)$settings);
$user->settings()->set('some.setting', 'new value');
$user->settings()->update('some.setting', 'new value');
//multiple
$user->settings()->setMultiple([
    'some.setting_1' => 'new value 1',
    'some.setting_2' => 'new value 2',
]);

#Check if the model has a specific setting

$user->settings()->has('some.setting');

#Remove a setting from a model

$user->settings()->delete('some.setting');
//multiple
$user->settings()->deleteMultiple([
    'some.setting_1',
    'some.setting_2',
]);
//all
$user->settings()->clear();

#Persistence for settings field

In case of field settings the auto-save is configurable.

The default value is true

• Use an attribute on model

protected $persistSettings = true; //boolean

• Environment (.env) variable

MODEL_SETTINGS_PERSISTENT=true

• Config value - model settings config file

'settings_persistent' => env('MODEL_SETTINGS_PERSISTENT', true),

If the persistence is false you have to save the model after the operation.

#Using another method name other than settings()

If you prefer to use another name other than settings , you can do so by defining a $invokeSettingsBy property. This forward calls (such as configurations()) to the settings() method.

#Validation system for settings data <a name="validation>

When you're using the set() or apply()|update() methods thrown an exception when you break a rule. You can define rules on model using $settingsRules public property, and the rules array definition is identical with the Laravel default validation rules. (see Laravel rules)

class User extends Model
{
    use HasSettingsTable;
 
    public array $defaultSettings = [
        'user' => [
            'name' => 'Test User',
            'email' => 'user@test.com'
            'age' => 27,
        ],
        'language' => 'en',
        'max_size' => 12,
    ];
 
    // settings rules
    public array $settingsRules = [
        'user' => 'array',
        'user.email' => [
            'string',
            'email',
        ],
        'user.age' => 'integer',
        'language' => 'string|in:en,es,it|max:2',
        'max_size' => 'int|min:5|max:15',
    ];
}

#Changelog

Please see CHANGELOG for more information what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#License

The MIT License (MIT). Please see LICENSE for more information.

#Related Stuff

• LaraNews - Laravel Model Settings
• made with Laravel - Laravel Model Settings