chapdel / model-settings-for-laravel
Model Settings for your Laravel app
Installs: 137
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Type:laravel-package
Requires
- php: ^8.1
- ext-json: *
- illuminate/cache: ^10.0
- illuminate/config: ^10.0
- illuminate/console: ^10.0
- illuminate/database: ^10.0
- illuminate/filesystem: ^10.0
- illuminate/support: ^10.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.14
- josiasmontag/laravel-redis-mock: ^1.2
- orchestra/testbench: ^8.0
- phpunit/phpunit: ^9.5.10
Suggests
- predis/predis: Required to use settings with Redis
README
Model Settings for your Laravel app
The package requires PHP 8+ 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
- Default Settings
- Usage
- Check id 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 id 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.