glorand/laravel-model-settings

The package requires PHP 8.2+ and Laravel 12+, 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
• Upgrading from v8
• Updating your Eloquent Models
  • Choosing the driver
  • The field driver
  • The table driver
  • The redis driver
  • Custom drivers
• 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": "^9.0"
    }
}

Upgrading from v8

Version 9 replaces the three storage-specific traits with a single HasSettings trait and a configuration-driven driver system. See the migration guide for the full checklist.

Env (config) variables (.env file)

The storage driver used by every model that does not declare its own (field | table | redis)

MODEL_SETTINGS_DRIVER=field

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

MODEL_SETTINGS_FIELD_NAME=settings

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

MODEL_SETTINGS_TABLE_NAME=model_settings

Optional, for the redis driver (named connection, empty = default; storage key prefix)

MODEL_SETTINGS_REDIS_CONNECTION=
MODEL_SETTINGS_REDIS_PREFIX=r-k-

Updating your Eloquent Models

Your models should use the HasSettings trait.

use Glorand\Model\Settings\Traits\HasSettings;

class User extends Model
{
    use HasSettings;
}

Choosing the driver

The storage backend is picked by a driver, not by the trait. The default driver is field; set it app-wide via the MODEL_SETTINGS_DRIVER env variable (or the driver config key), and per model via the $settingsDriver property - the model property always wins:

class User extends Model
{
    use HasSettings;

    protected $settingsDriver = 'table'; // 'field' (default) | 'table' | 'redis'
}

The field driver

Stores settings in a JSON column on the model's own table. Run the command below in order to create a migration file for a table.

php artisan model-settings:model-settings-field

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\HasSettings;

class User extends Model
{
    use HasSettings;

    //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';

}

The table driver

Stores settings in a separate table, one row per model. Run the command below to create the settings table.

 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\HasSettings;

class User extends Model
{
    use HasSettings;

    protected $settingsDriver = 'table';
}

The redis driver

Stores settings in Redis.

use Glorand\Model\Settings\Traits\HasSettings;

class User extends Model
{
    use HasSettings;

    protected $settingsDriver = 'redis';
}

Custom drivers

You can add your own storage backend without touching the package. Either register the manager class statically in the config:

'drivers' => [
    // ...
    'dynamodb' => [
        'class' => \App\Settings\DynamoDbSettingsManager::class, // extends AbstractSettingsManager
    ],
],

…or at runtime, e.g. in a service provider:

use Glorand\Model\Settings\SettingsManagerFactory;

app(SettingsManagerFactory::class)->extend('dynamodb', function ($model) {
    return new DynamoDbSettingsManager($model);
});

Then point any model at it: protected $settingsDriver = 'dynamodb';. A custom driver reads its own drivers.<name>.* config namespace.

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\HasSettings;

class User extends Model
{
    use HasSettings;

    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 the field driver 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

'drivers' => [
   'field' => [
       // ...
       '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

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 HasSettings;

    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