laravel-model-settings

Model Settings for your Laravel app

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
  • The cache 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 | cache)

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-

Optional, for the cache driver (named store, empty = default; lifetime in minutes, empty = forever; storage key prefix)

MODEL_SETTINGS_CACHE_STORE=
MODEL_SETTINGS_CACHE_TTL=
MODEL_SETTINGS_CACHE_PREFIX=c-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' | 'cache'
}

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

The cache driver

Stores settings through Laravel's Cache facade, so any store configured in config/cache.php (Memcached, DynamoDB, database, file, ...) can back them. Use MODEL_SETTINGS_CACHE_STORE to pick a named store; leave it empty to use the application's default store.

use Glorand\Model\Settings\Traits\HasSettings;

class User extends Model
{
    use HasSettings;

    protected $settingsDriver = 'cache';
}

Settings are stored forever by default, because for this driver the cache is the only copy of the data. MODEL_SETTINGS_CACHE_TTL sets an expiry in minutes if you want one - note that the lifetime is only refreshed when the settings are written, never when they are read, so an expiring value will disappear even from a model whose settings are read constantly. A 0 or negative TTL throws a ModelSettingsException rather than silently discarding every write.

Two things to keep in mind before choosing this driver: anything that flushes the store (php artisan cache:clear, Cache::flush()) erases the settings of every model using it, and stores that evict under memory pressure can drop them at any time. If the settings must survive that, use the field or table driver.

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..* 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' => '[email protected]'
            '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