sashalenz/laravel-settings-ui

Laravel Settings UI

Declarative, nestable runtime settings for Laravel — fluent schema, pluggable stores, secure secrets, resilient cache, transparent config() overlay, and a bundled responsive admin UI built with Livewire and Tailwind CSS.

✨ Features

• Code-Authoritative Declarations: Settings are defined in strongly typed PHP classes, never in the database.
• Zero-Coupling config() Overlay: Application code continues to read config('group.key') without any dependency on the settings machinery.
• Deep Hierarchical Nesting: Groups, subgroups, cards, sections, and fields mirror full dotted paths (group.section.key).
• Pluggable Storage Backends: Database, Encrypted Database, File (JSON/YAML), and external Secret Stores (Vault, AWS Secrets Manager, etc.).
• Pluggable & Secure Secrets Engine:
  • Masked values in HTML and Livewire states.
  • Zero-plaintext leaks in logs and exception traces.
  • Rate-limited and permission-gated "Click to Reveal" action.
• Resilient & Stampede-Protected Cache:
  • Stores primitive values only (zero risk of __PHP_Incomplete_Class serialization bugs).
  • Schema fingerprinting & version-stamped keys.
  • Cache stampede prevention via cache locks.
  • Queue worker / Octane auto-refresh hooks.
• Full Audit History & Revert:
  • Automatically records user, timestamp, before/after values, and source.
  • One-click rollback to prior versions.
• Modular & Domain Discovery:
  • Register settings from packages, modules, or domains (Settings::register(...) or Settings::discover(...)).
  • Composer extra.laravel-settings discovery.
• Seeder Engine & CLI:
  • SettingsSeeder for idempotent seeding (syncMissing() and forceSync()).
  • Artisan commands: settings:sync, settings:seed, settings:doctor, settings:clear-cache.

📦 Installation

Install via Composer:

composer require sashalenz/laravel-settings-ui

Publish configuration and migrations:

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

🚀 Quick Start

1. Declare a Setting Schema

Create a schema class implementing DeclaresSettings:

namespace App\Settings;

use SashaLenz\SettingsUi\Contracts\DeclaresSettings;
use SashaLenz\SettingsUi\Schema\Field;
use SashaLenz\SettingsUi\Schema\Group;

final class GeneralSettings implements DeclaresSettings
{
    public function schema(): Group
    {
        return Group::make('general')
            ->label('General Settings')
            ->icon('heroicon-o-cog')
            ->fields([
                Field::text('site_name')
                    ->label('Website Name')
                    ->default('My App')
                    ->rules(['required', 'string', 'max:255']),

                Field::boolean('maintenance_mode')
                    ->label('Maintenance Mode')
                    ->default(false),

                Field::text('api_token')
                    ->label('API Secret Token')
                    ->secret()
                    ->store('secrets'),
            ]);
    }
}

2. Register the Schema

In your config/settings.php:

'schemas' => [
    \App\Settings\GeneralSettings::class,
],

Or programmatically in any ServiceProvider:

use SashaLenz\SettingsUi\Facades\Settings;

public function boot(): void
{
    Settings::register([
        \App\Settings\GeneralSettings::class,
    ]);

    // Or discover all settings across domain modules:
    Settings::discover([
        app_path('Domain/*/Settings'),
    ]);
}

3. Read Values Transparently

// Stored database value automatically overlays config file default:
$siteName = config('general.site_name');

// Or using the Settings facade:
$siteName = Settings::get('general.site_name');

🔐 Secrets Management

Mark fields as secret to encrypt them and prevent plaintext exposure in forms and logs:

Field::text('stripe_secret')
    ->secret()
    ->store('secrets')

Supported Drivers:

• encrypted-db: Encrypted locally in your database using Laravel's APP_KEY.
• env: Resolves from .env environment variables.
• vault: HashiCorp Vault KV v1/v2 engine.
• aws: AWS Secrets Manager.

🌱 Seeding Settings

Seed declared defaults safely without overwriting existing settings:

use SashaLenz\SettingsUi\Database\Seeders\SettingsSeeder;

class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        $this->call(SettingsSeeder::class);
    }
}

Or via Artisan CLI:

php artisan settings:seed
php artisan settings:seed --group=general --force

🖥 Admin UI

Mount the routes in your routes file (e.g., routes/web.php):

use SashaLenz\SettingsUi\Facades\Settings;

Route::prefix('admin')->middleware(['web', 'auth'])->group(function () {
    Settings::routes();
});

Available routes:

• /admin/settings — List of setting groups
• /admin/settings/{group} — Group editor form
• /admin/settings/history — Audit change log & revert
• /admin/settings/schema — Read-only schema inspector

🧪 Testing

composer test
composer format
composer analyse

📄 License

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