README

Polymorphic, typed key/value settings for any Eloquent model.

Drop the HasSettings trait onto any model and instantly get a bag of settings stored in a single polymorphic table. Values keep their PHP type — booleans come back as booleans, arrays as arrays, integers as integers — without you having to think about casting.

$user->setSetting('theme', 'dark');
$user->setSetting('notifications', true);
$user->setSetting('limits', ['daily' => 100, 'monthly' => 2000]);

$user->setting('theme');          // "dark"
$user->setting('notifications');  // true  (bool)
$user->setting('limits');         // ['daily' => 100, 'monthly' => 2000]
$user->setting('missing', 'n/a'); // "n/a" (default)

Installation

composer require stechstudio/laravel-settings

Publish and run the migration:

php artisan vendor:publish --tag=settings-migrations
php artisan migrate

The package auto-registers its service provider. The migration is also loaded automatically, so in development you can migrate without publishing — publish it when you want the file committed to your app.

Optionally publish the config:

php artisan vendor:publish --tag=settings-config

Usage

Add the trait to any model:

use STS\Settings\Concerns\HasSettings;

class User extends Authenticatable
{
    use HasSettings;
}

Reading & writing

// Write — the cast type is auto-detected from the value
$user->setSetting('theme', 'dark');

// Read, with an optional default
$user->setting('theme');             // "dark"
$user->setting('missing', 'default'); // "default"

// Existence
$user->hasSetting('theme');          // true

// Delete
$user->deleteSetting('theme');       // true

// Everything as a name => value map
$user->allSettings();                // ['theme' => 'dark', ...]

// Increment a numeric setting (creates it at $amount if absent)
$user->incrementSetting('login_count');     // +1
$user->incrementSetting('credits', 25);     // +25

Type casting

Types are detected automatically on write (bool, int, float, array, string). Pass an explicit cast as the third argument when you need to override detection — for example to store a numeric string as a string:

use STS\Settings\Models\Setting;

$user->setSetting('zip', '90210', Setting::CAST_STRING);
$user->setting('zip'); // "90210" (stays a string)

Available casts: Setting::CAST_STRING, CAST_INT, CAST_FLOAT, CAST_BOOL, CAST_ARRAY, CAST_JSON.

The relationship

HasSettings adds a standard settings() morph-many relationship, so you can eager load and query it like any other:

$users = User::with('settings')->get();

Settings are scoped to their owner — each model only ever sees its own.

Configuration

config/settings.php:

return [
    // The table that holds settings rows.
    'table' => 'settings',

    // The model representing a single setting. Point this at your own
    // subclass of STS\Settings\Models\Setting to add scopes or behaviour.
    'model' => STS\Settings\Models\Setting::class,
];

Testing

composer test

License

MIT. See LICENSE.md.