dragon-code/laravel-model-settings

Model Settings for your Laravel application

dev-main 2026-07-07 23:15 UTC

Requires

• php: ^8.3
• illuminate/database: ^12.0 || ^13.0
• illuminate/support: ^12.0 || ^13.0

Requires (Dev)

• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• pestphp/pest-plugin-type-coverage: ^4.0

MIT

• Andrey Helldar

• Settings
• model-settings
• laravel-model-settings

Published on Packagist.org on 2026-07-07 23:15 UTC

README

Store settings for individual Eloquent models, with optional defaults shared by models of the same type.

Use this package when each model needs its own settings, but should fall back to shared values when a model value is missing.

Installation

Install the package via Composer:

composer require dragon-code/laravel-model-settings

Publish the config and migration, then run migrations:

php artisan vendor:publish --tag="model-settings"
php artisan migrate

Quick Start

Add the HasSettings trait to a model:

use DragonCode\LaravelModelSettings\Concerns\HasSettings;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use HasSettings;
}

Use settings on a saved model:

$user = User::query()->findOrFail(123);

$user->settings()->set('timezone', 'UTC');
$user->settings()->set('notifications', ['email' => true]);

$user->settings()->get('timezone');      // 'UTC'
$user->settings()->get('notifications'); // ['email' => true]
$user->settings()->get('missing');       // null

$user->settings()->all();                // Illuminate\Support\Collection

$user->settings()->forget('timezone');
$user->settings()->get('timezone');      // null

Default Settings

Default settings are fallback values shared by models of the same type:

$defaults = (new User)->defaultSettings();

$defaults->set('timezone', 'UTC');
$defaults->set('locale', 'en');

$defaults->get('timezone'); // 'UTC'
$defaults->all();           // Illuminate\Support\Collection
$defaults->forget('locale');

Model values override defaults. Removing the model value exposes the default again:

(new User)->defaultSettings()->set('timezone', 'UTC');

$user->settings()->get('timezone'); // 'UTC'

$user->settings()->set('timezone', 'Europe/Paris');
$user->settings()->get('timezone'); // 'Europe/Paris'

$user->settings()->forget('timezone');
$user->settings()->get('timezone'); // 'UTC'

Default settings are stored with the model morph class and item_id = 0.

API

Method	Returns	Description
all()	Collection	Returns defaults merged with model settings. Model values win.
get(UnitEnum|string|int $key)	mixed	Returns the model value, then the default value, then null.
set(UnitEnum|string|int $key, mixed $value)	void	Creates or updates a model setting.
forget(UnitEnum|string|int $key)	void	Removes a model setting.

Setting Keys

Keys can be strings, integers, or PHP enums:

enum UserSetting: string
{
    case Timezone = 'timezone';
}

$user->settings()->set(UserSetting::Timezone, 'UTC');
$user->settings()->get(UserSetting::Timezone); // 'UTC'

get() treats blank model values as missing and falls back to defaults. This includes null, an empty string, and an empty array.

Configuration

After publishing, edit config/model-settings.php:

Option	Environment variable	Default
model	-	DragonCode\LaravelModelSettings\Models\Settings::class
connection	MODEL_SETTINGS_DATABASE_CONNECTION	env('DATABASE_CONNECTION')
table	MODEL_SETTINGS_DATABASE_TABLE	settings

The migration stores settings in one table with item_type, string item_id, key, and nullable JSON payload. Each setting is unique by item_type, item_id, and key.

Testing

composer test
composer test:coverage

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail [e-mail] instead of using the issue tracker.

Credits

• Andrey Helldar
• All Contributors

License

The MIT License (MIT). Please see License File for more information.