README

Simple settings for Laravel apps.

Easily give multiple resources settings
Simple to add additional settings as your app grows
Set default settings and limit setting values for security
Fully configurable

Upgrade Information
About
Install
Usage
Methods
Validation Rules
Advanced Configuration
Contributing

Upgrade Information

From 1.3.* to 1.4.0

1.4.0 drops support for PHP 7.1 and adds support for Laravel 6.

From 1.2.* to 1.3.0

1.3.0 drops support for PHP 7.0.

From 1.1.* to 1.2.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.

From 1.0.* to 1.1.0

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.*

From 0.9.* to 1.0.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.

About

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.

Install

1. Install through composer

composer require zachleigh/laravel-property-bag

Laravel Installation

a. Register the service provider

In Laravel's config/app.php file, add the service provider to the array with the 'providers' key.

LaravelPropertyBag\ServiceProvider::class

b. Publish the migration

php artisan vendor:publish --provider="LaravelPropertyBag\ServiceProvider"

Lumen Installation

a. Enable Eloquent

If you haven't already done so, find and uncomment $app->withEloquent() in app/boostrap.php.

b. Register the service provider

In Lumen's app/bootstrap.php file, add the service provider:

$app->register(LaravelPropertyBag\ServiceProvider::class);

c. Copy migration file

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.

2. Run the migration

php artisan migrate

3. Create a new settings config file for your resource.

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.

Usage

1. Use the trait in the model.

...
use LaravelPropertyBag\Settings\HasSettings;

class User extends Model
{
    use HasSettings;

    ...
}

2. Register your settings plus their allowed values and defaults

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.

3. Set the setting from the user model

$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'
]);

4. Get the set value from the user model

$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.

Methods

get($key)

Get value for given key.

$value = $model->settings()->get($key);

set($array)

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'
]);

getDefault($key)

Get default value for given key.

$default = $model->settings()->getDefault($key);

// or

$default = $model->defaultSetting($key);

allDefaults()

Get all the default values for registered settings. Returns collection.

$defaults = $model->settings()->allDefaults();

// or

$defaults = $model->defaultSetting();

getAllowed($key)

Get allowed values for given key. Returns collection.

$allowed = $model->settings()->getAllowed($key);

// or

$allowed = $model->allowedSetting($key);

allAllowed()

Get all allowed values for registered settings. Returns collection.

$allowed = $model->settings()->allAllowed();

// or

$allowed = $model->allowedSetting();

isDefault($key, $value)

Return true if given value is the default value for given key.

$boolean = $model->settings()->isDefault($key, $value);

isValid($key, $value)

Return true if given value is allowed for given key.

$boolean = $model->settings()->isValid($key, $value);

all()

Return all setting value's for model. Returns collection.

$allSettings = $model->settings()->all();

// or

$allSettings = $model->allSettings();

keyIs($key, $value)

Return true if setting for given key equals given value.

$boolean = $model->settings()->keyIs($key, $value);

reset($key)

Reset key to default value.

$default = $model->settings()->reset($key);

withSetting($key, $value = null)

Get an array with all stored rows with a given setting and/or value.

$collection = $model::withSetting($key);
// or
$collection = $model::withSetting($key, $value);

Validation Rules

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
]

Available Rules

':any:'

Any value will be accepted.

':alpha:'

Alphabetic values will be accepted.

':alphanum:'

Alphanumeric values will be accepted.

':bool:'

Boolean values will be accepted.

':int:'

Integer values will be accepted.

':num:'

Numeric values will be accepted.

':range=low,high:'

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.

':string:'

Strings will be accepted.

User Defined Rules

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:'.

Advanced Configuration

Laravel Property Bag gives you several ways to configure the package to fit your needs and wants.

I don't want to register settings as an array

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
]

I want to use dynamic allowed and default values.

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]
        ]
    ]);
}

Contributing

Contributions are more than welcome. Fork, improve and make a pull request. For bugs, ideas for improvement or other, please create an issue.

zachleigh / laravel-property-bag

Maintainers

Details