1.4.0 drops support for PHP 7.1 and adds support for Laravel 6.
1.3.0 drops support for PHP 7.0.
1.2.0 drops support for PHP 5.6. It will likely still work in older PHP versions, but bugs or issues that focus specifically on 5.6 or lower will no longer be dealt with. Support for PHP 7.2 added.
1.1.0 adds Lumen support and support for Laravel 5.4 (thanks tzurbaev). There should be no breaking changes. If using Laravel 5.3, please use Version 1.0.5:
composer require zachleigh/laravel-property-bag:1.0.*
Version 1.0.0 brings major changes to the package that make it incompatible with previous versions. The package was essentially rewritten making upgrade from 0.9.7 to 1.0.0 difficult at best.
Laravel Property Bag gives your application resources savable, secure settings by using a single database property bag table. The benefit of using this kind of settings table, as opposed to say a json blob column on the resource table, is that if in the future you decide to change a setting value, a simple database query can easily take care of it.
composer require zachleigh/laravel-property-bag
In Laravel's config/app.php file, add the service provider to the array with the 'providers' key.
LaravelPropertyBag\ServiceProvider::class
php artisan vendor:publish --provider="LaravelPropertyBag\ServiceProvider"
If you haven't already done so, find and uncomment $app->withEloquent()
in app/boostrap.php
.
In Lumen's app/bootstrap.php file, add the service provider:
$app->register(LaravelPropertyBag\ServiceProvider::class);
Since Lumen doesn't offer the php artisan vendor:publish
command, you have to copy the migration file manually from the vendor/zachleigh/laravel-property-bag/src/Migrations
directory to the database/migrations
directory.
php artisan migrate
php artisan pbag:make {resource}
{resource} should be the name of the model you wish to add settings to. For example:
php artisan pbag:make User
This will create a Settings directory containing a UserSettings class where you can configure your settings for the User class.
...
use LaravelPropertyBag\Settings\HasSettings;
class User extends Model
{
use HasSettings;
...
}
After publishing the UserSettings file (hopefully you did this above), register settings in the UserSettings class.
protected $registeredSettings = [
'example_setting' => [
'allowed' => [true, false],
'default' => false
]
];
Each setting must contain an array of allowed values and a default value. It is also possible to use validation rules instead of hardcoding allowed values.
$user->settings(['example_setting' => false]);
// or
$user->settings()->set(['example_setting' => false]);
// or
$user->setSettings(['example_setting' => false]);
Set multiple values at a time
$user->settings([
'example_setting' => false,
'another_setting' => 'grey'
]);
$value = $user->settings('example_setting');
// or
$value = $user->settings()->get('example_setting');
If the value has not been set, the registered default value will be returned. Note that default values are not stored in the database in order to limit database size.
Get value for given key.
$value = $model->settings()->get($key);
Set array keys to associated values. Values may be of any type. Returns Settings.
When a default value is passed to set(), it will not be stored in the database. Don't be alarmed if your default values aren't showing up in the table.
If a value is not registered in the allowed values array, a LaravelPropertyBag\Exceptions\InvalidSettingsValue
exception will be thrown. You can use the $e->getFailedKey()
method to retrieve the failed setting name.
$model->settings()->set([
'key1' => 'value1',
'key2' => 'value2'
]);
// or
$model->setSettings([
'key1' => 'value1',
'key2' => 'value2'
]);
Get default value for given key.
$default = $model->settings()->getDefault($key);
// or
$default = $model->defaultSetting($key);
Get all the default values for registered settings. Returns collection.
$defaults = $model->settings()->allDefaults();
// or
$defaults = $model->defaultSetting();
Get allowed values for given key. Returns collection.
$allowed = $model->settings()->getAllowed($key);
// or
$allowed = $model->allowedSetting($key);
Get all allowed values for registered settings. Returns collection.
$allowed = $model->settings()->allAllowed();
// or
$allowed = $model->allowedSetting();
Return true if given value is the default value for given key.
$boolean = $model->settings()->isDefault($key, $value);
Return true if given value is allowed for given key.
$boolean = $model->settings()->isValid($key, $value);
Return all setting value's for model. Returns collection.
$allSettings = $model->settings()->all();
// or
$allSettings = $model->allSettings();
Return true if setting for given key equals given value.
$boolean = $model->settings()->keyIs($key, $value);
Reset key to default value.
$default = $model->settings()->reset($key);
Get an array with all stored rows with a given setting and/or value.
$collection = $model::withSetting($key);
// or
$collection = $model::withSetting($key, $value);
Rather than hardcoding values in an array, it is also possible to define rules that determine whether a setting value is valid. Rules are always strings and must contain a colon at both the beginning and ending of the string.
'integer' => [
'allowed' => ':int:',
'default' => 7
]
In this case, the setting value saved for the 'integer' key must be an integer.
Some rules require parameters. Parameters can be passed in the rule definition by using an equal sign and a comma separated list.
'range' => [
'allowed' => ':range=1,5:',
'default' => 1
]
Any value will be accepted.
Alphabetic values will be accepted.
Alphanumeric values will be accepted.
Boolean values will be accepted.
Integer values will be accepted.
Numeric values will be accepted.
Numeric values falling between or inluding the given low and high parameters will be accpeted. Example:
'range' => [
'allowed' => ':range=1,10:',
'default' => 5
]
The numbers 1 to 10 will be allowed.
Strings will be accepted.
To make user defined rules, first publish the Rules file to Settings/Resources/Rules.php:
php artisan pbag:rules
Rule validation methods should be named by prepending 'rule' to the rule name. For example, if our rule is 'example', we would define it in the settings config file like this:
'setting_name' => [
'allowed' => ':example:',
'default' => 'default'
]
And then our method would be called 'ruleExample':
public static function ruleExample($value)
{
// do stuff
//
// return boolean;
}
All rule methods should be static and thus should not care about object or application state. If your rule requires parameters, accept them as arguments to the method.
'setting_name' => [
'allowed' => ':example=arg1,arg2:',
'default' => 'default'
]
public static function ruleExample($value, $arg1, $arg2)
{
// do stuff
//
// return boolean;
}
Another option would be to validate input with Laravel's built in validation, which is much more complete than what this package offers, and then set all your setting allowed values to ':any:'.
Laravel Property Bag gives you several ways to configure the package to fit your needs and wants.
Cool. I get it. Especially if you have dozens of settings, dealing with an array can be annoying. In the model settings config file, add the registeredSettings method.
/**
* Return a collection of registered settings.
*
* @return Collection
*/
public function registeredSettings()
{
// Your code
return $collection;
}
In this method, do whatever you want and return a collection of items that has the same structure as the registeredSettings array.
'example_setting' => [
'allowed' => [true, false],
'default' => true
]
No problem. Like in the above section, create your own registeredSettings method in the settings config file and return a collection of registered settings.
/**
* Return a collection of registered settings.
*
* @return Collection
*/
public function registeredSettings()
{
$allGroups = Auth::user()->allGroupNames();
return collect([
'default_group' => [
'allowed' => $allGroups,
'default' => $allGroups[0]
]
]);
}
The allGroupNames function simply returns an array of group names:
/**
* Get array of all group names.
*
* @return array
*/
public function allgroupNames()
{
return $this->groups->pluck('name')->all();
}
You can also access the model the settings are attached to with the getResource()
method.
/**
* Return a collection of registered settings.
*
* @return Collection
*/
public function registeredSettings()
{
$allGroups = getResource()->allGroupNames();
return collect([
'default_group' => [
'allowed' => $allGroups,
'default' => $allGroups[0]
]
]);
}
Contributions are more than welcome. Fork, improve and make a pull request. For bugs, ideas for improvement or other, please create an issue.