Eloquent Settings

A Laravel package that adds simple but flexible JSON-based settings management to Eloquent models.

Requirements

• PHP ^8.2
• Laravel ^12.0 | ^13.0

Installation

composer require x-laravel/eloquent-settings

The service provider is registered automatically via Laravel's package discovery.

Setup

1. Migration

Add the settings column to your table using the settingsBag() Blueprint macro:

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->settingsBag(); // adds a nullable JSON settings column
    $table->timestamps();
});

2. Model

Add the HasSettingsBag trait to your model:

use Illuminate\Database\Eloquent\Model;
use XLaravel\EloquentSettings\HasSettingsBag;

class User extends Model
{
    use HasSettingsBag;
}

Usage

Get all settings

$user->settings()->all(); // ['theme' => 'dark', 'lang' => 'tr']

Get a specific setting

$user->settings()->get('theme');           // 'dark'
$user->settings()->get('theme', 'light'); // default value if missing
$user->settings()->get('layout.boxed');   // dot notation for nested keys

Check if a setting exists

$user->settings()->has('theme');        // true / false
$user->settings()->has('layout.boxed'); // dot notation supported

Add or update a setting

$user->settings()->update('theme', 'dark');
$user->settings()->update('layout.boxed', true); // dot notation for nested keys

Delete a setting

$user->settings()->delete('theme');        // removes one setting
$user->settings()->delete('layout.boxed'); // dot notation supported
$user->settings()->delete();              // clears all settings

Replace all settings

$user->settings()->apply(['theme' => 'dark', 'lang' => 'tr']);

All methods except all(), get(), and has() return $this for chaining:

$user->settings()
    ->update('theme', 'dark')
    ->update('lang', 'tr');

Multiple Setting Groups

A model can delegate settings to a related model, keeping different concerns separate.

1. Create a related settings table

Schema::create('user_theme_settings', function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger('user_id');
    $table->settingsBag();
    $table->timestamps();
});

2. Create the related model

use Illuminate\Database\Eloquent\Model;
use XLaravel\EloquentSettings\HasSettingsBag;

class UserThemeSetting extends Model
{
    use HasSettingsBag;
}

3. Define the relationship on the parent model

class User extends Model
{
    use HasSettingsBag;

    public function themeSettings()
    {
        return $this->hasOne(UserThemeSetting::class);
    }
}

4. Access the related settings

$user->settings('theme')->get('layout.boxed');
$user->settings('theme')->update('color', 'blue');
$user->settings('theme')->delete('color');

If the related record does not exist yet, it is created automatically on the first update() or apply() call.

Default Settings

Define $defaultSettings on your model to provide fallback values when no settings have been saved:

class User extends Model
{
    use HasSettingsBag;

    protected $defaultSettings = [
        'theme' => 'light',
        'notifications' => true,
    ];
}

$user = User::create([]); // settings initialised from $defaultSettings automatically
$user->settings()->get('theme'); // 'light'

Allowed Settings

Define $allowedSettings to restrict which keys can be persisted. Any other keys are silently dropped on save:

class User extends Model
{
    use HasSettingsBag;

    protected $allowedSettings = ['theme', 'language'];
}

$user->settings()->apply(['theme' => 'dark', 'language' => 'tr', 'other' => 'ignored']);
$user->settings()->all(); // ['theme' => 'dark', 'language' => 'tr']

Method Alias

If you prefer a different method name instead of settings(), define $mapSettingsTo:

class User extends Model
{
    use HasSettingsBag;

    protected $mapSettingsTo = 'config';
}

$user->config()->get('theme');
$user->config('theme')->update('color', 'blue');

Testing

# Build first (once per PHP version, or after composer.json changes)
docker compose --profile php82 up --build

# Run tests
docker compose --profile php82 up
docker compose --profile php83 up
docker compose --profile php84 up
docker compose --profile php85 up

License

This package is open-sourced software licensed under the MIT license.