- Easily give multiple resources settings
- Simple to add additional settings as your app grows
- Set default settings and limit setting values for security
- Add Title and Description to settings, so users can understand better what it is or what it does
- Upgrade Information
- About
- Install
- Usage
- Methods
- Validation Rules
- Advanced Configuration
- Testing
- Contributing
Caution
This update is incompatible with previous releases since it changes the structure of the settings
When using $model->allowedSetting($key), it now returns an 'allowed' key with an array of all allowed values for the setting, plus a title and description keys which can be used to enhance info about the setting. If no key is provided, it returns an array of settings, each one with this new configuration
protected $registeredSettings = [
'test_settings1' => [
'allowed' => ['bananas', 'grapes', 8, 'monkey'],
'default' => 'monkey',
'title' => 'Test Setting 1',
'description' => 'This is a test setting.',
],
];Update dev dependencies to match:
php: "^8.1"
laravel/laravel: "^10.3"
orchestra/testbench: "^8.21",
phpunit/phpunit: "^10.1",
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.
Since this is a frok from the original project by zachleigh/laravel-property-bag, if you plan to include this this fork in your project you must include the original package using the dev-master branch, and also include this repository into the composer.json file of your app
...
"repositories": [
{
"type": "vcs",
"url": "https://github.com/lanea07/laravel-property-bag",
},
],
...
"require": {
...
"zachleigh/laravel-property-bag": "dev-master",
...
},
...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"
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 register settings in the UserSettings class.
protected $registeredSettings = [
'test_settings1' => [
'allowed' => ['bananas', 'grapes', 8, 'monkey'],
'default' => 'monkey',
'title' => 'Test Setting 1',
'description' => 'This is a test setting.',
],
];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.
The title and description keys are used to offer a better understanding of the setting. You can use this, for example, in a frontend where users can change its own settings...
$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. This rule also applies to title and description keys.
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.
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
'title' => 'A Title',
'description' => 'What this setting is or does'
]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]
]
]);
}This upgrade uses laravel's latest testing package 🔗 Orchestral Testbench, so after running composer install it is recomended to follow instructions about how to setup this package before running tests.
Contributions are more than welcome. Fork, improve and make a pull request. For bugs, ideas for improvement or other, please create an issue.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent