Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Model Settings for your Laravel app

Total Downloads
Latest Stable Version 'Github Actions Build Status Software License maintainability
StyleCI Scrutinizer Code Quality Scrutinizer Code Coverage
PHP Version

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


$ 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


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


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.


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

Check id the settings for the entity is empty


Check settings (exist)


Get all model's settings


Get a specific setting

$user->settings()->get('some.setting', 'default value');
	'default value'

Add / Update setting

$user->settings()->set('some.setting', 'new value');
$user->settings()->update('some.setting', 'new value');
	'some.setting_1' => 'new value 1',
	'some.setting_2' => 'new value 2',

Check if the model has a specific setting


Remove a setting from a model


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
  • 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' => ''
            'age' => 27,
        'language' => 'en',
        'max_size' => 12,

    // settings rules
    public array $settingsRules = [
        'user' => 'array',
        '' => [
        'user.age' => 'integer',
        'language' => 'string|in:en,es,it|max:2',
        'max_size' => 'int|min:5|max:15',


Please see CHANGELOG for more information what has changed recently.


Please see CONTRIBUTING for details.


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

Related Stuff