Looking to hire Laravel developers? Try LaraJobs

laravel-settings maintained by egough

Description
Database-backed application and model settings for Laravel.
Author
Last update
2026/10/31 17:19 (dev-main)
License
Downloads
1 203

Comments
comments powered by Disqus

alt text

Latest Version on Packagist Total Downloads License Tests

Database-backed application and model settings for Laravel.

Provides a simple, typed and cacheable way to store dynamic configuration outside of .env and static config files, including per-model settings such as user or team preferences.


Quick Example

// Application setting
settings()->set('site.name', 'My Application');

settings()->get('site.name');


// Model-specific setting
$user->settings()->set('ui.theme', 'dark');

$user->settings()->get('ui.theme');


// Feature flag
if (flag('billing.enabled')) {
    // Feature enabled
}

Blade usage:

@hasFlag('billing.enabled')
    <x-billing-panel />
@endhasFlag

<title>@setting('site.name')</title>

When Should I Use This Package?

Use this package when your application needs configuration that can change at runtime without modifying environment variables or deployment configuration.

Typical use cases include:

Application settings

  • Site name or branding
  • Feature toggles
  • Maintenance or runtime configuration
  • Admin-managed options

Model settings

  • User preferences (theme, notifications, dashboard layout)
  • Team or organisation configuration
  • Account-specific options
  • Per-project or per-resource metadata

This package is intended for dynamic configuration stored in the database and accessed consistently across your application.


When Not to Use It

You should continue using Laravel configuration or environment variables for:

  • Database credentials
  • API keys and secrets
  • Environment-specific infrastructure configuration
  • Values required during application boot

In general:

  • .env → infrastructure and secrets
  • config/*.php → static application configuration
  • egough/laravel-settings → runtime, database-driven configuration

Installation

composer require egough/laravel-settings:^1.0

Publish configuration and migrations:

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

Application Settings

Global settings are accessible anywhere in your application.

Helper

settings()->set('site.name', 'My Application');

settings()->get('site.name');

Facade

use Settings;

Settings::set('site.name', 'My Application');
Settings::get('site.name');

Dependency Injection

use Egough\LaravelSettings\SettingsManager;

public function __construct(
    private SettingsManager $settings
) {}

$this->settings->get('site.name');

Model Settings

Settings can be attached to any Eloquent model.

Add the trait:

use Egough\LaravelSettings\Traits\HasSettings;

class User extends Model
{
    use HasSettings;
}

Usage:

$user = User::find(1);

$user->settings()->set('ui.theme', 'dark');

$user->settings()->get('ui.theme');

Retrieve all settings:

$user->settings()->all();

Remove a setting:

$user->settings()->forget('ui.theme');

Setting Events

Listen for stored setting changes using Laravel events:

use Egough\LaravelSettings\Events\SettingUpdated;
use Illuminate\Support\Facades\Event;

Event::listen(SettingUpdated::class, function (SettingUpdated $event): void {
    if ($event->key === 'notifications.enabled') {
        // React using $event->oldValue and $event->newValue.
        // $event->model is the owning model, or null for global settings.
    }
});
Event Public properties
SettingCreated key, newValue, model
SettingUpdated key, oldValue, newValue, model
SettingDeleted key, oldValue, model

Values are decoded from storage. Equal values and deleting a missing key emit nothing. Creating a stored override emits SettingCreated even when it matches a config default; stored null counts as an existing setting.

With the built-in repositories, events run after the settings database transaction commits and are discarded on rollback. Outside a transaction, they run immediately after cache invalidation. This applies to helpers, facades, managers, model settings, and settings:set. Direct repository, Eloquent, and SQL writes do not emit these events.

See the event documentation for transaction details and custom repository support.


Feature Flags

Feature flags are boolean settings.

flag('billing.enabled');

Flag::enabled('billing.enabled');

With fallback:

flag('beta.feature', false);

Blade Directives

@hasSetting('site.name')
@endhasSetting

@hasFlag('billing.enabled')
@endhasFlag

<title>@setting('site.name')</title>

Default Values

Define defaults in config/settings.php:

'defaults' => [
    'site.name' => 'Laravel App',
];

Lookup order:

  1. Database value
  2. Config default
  3. Provided fallback

Caching

Settings are cached automatically.

Clear cache manually:

php artisan settings:clear-cache

Testing

Install development dependencies:

composer install

Run the test suite:

composer test

Or run PHPUnit directly:

vendor/bin/phpunit

The package tests use a lightweight in-memory SQLite setup for repository integration coverage, so no external database service is required.


Artisan Commands

php artisan settings:get site.name
php artisan settings:set site.name "My App"
php artisan settings:clear-cache

Requirements

  • PHP 8.2+
  • Laravel 10, 11, 12, or 13

License

MIT