README

Flexible, polymorphic key-value settings for Laravel with multi-tenancy and cascading fallback support.

Features

• Polymorphic scope — attach settings to any Eloquent model (department, user, …) or store them tenant- or system-wide
• Three-level fallback — model-specific → tenant-wide → system-wide
• Filament multi-tenancy — tenant ID is resolved automatically via filament()->getTenant()
• Cache — all reads are cached forever; writes flush the relevant cache key
• app_setting() helper — ergonomic global shortcut

Requirements

• PHP 8.4+
• Laravel 11 or 12
• Optional: Filament v3+ (for automatic tenant resolution)

Installation

1. Require the package

composer require agroezinger/filament-app-settings

2. Publish and run the migration

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

This creates the app_settings table. The package registers itself automatically via Laravel's package auto-discovery — no manual provider registration needed.

3. Done

// Write a setting
app_setting()->set('site.name', 'My App');

// Read it back
$name = app_setting('site.name', 'Default');

Database schema

app_settings
  id            bigint unsigned auto_increment
  key           varchar
  value         json nullable
  model_id      bigint unsigned  default 0
  model_type    varchar          default 'system'
  tenant_id     bigint unsigned  default 0
  created_at / updated_at
  unique (key, model_id, model_type, tenant_id)

Basic usage

use Agroezinger\FilamentAppSettings\AppSettings;

$settings = app(AppSettings::class);

// Write
$settings->set('invoice.footer', 'All prices include VAT.');

// Read (with optional default)
$footer = $settings->get('invoice.footer', '');

// Check existence
$settings->has('invoice.footer'); // true

// Delete by setting to null or ''
$settings->set('invoice.footer', null);

Global helper

// Returns the value directly
$value = app_setting('invoice.footer', 'default');

// Returns the AppSettings instance when called without arguments
app_setting()->set('foo', 'bar');
app_setting()->setMany([...]);

Model-scoped settings

$department = Department::find(1);

$settings->set('color', '#ff0000', model: $department);
$settings->get('color', null, model: $department);

Bulk write

$settings->setMany([
    ['key' => 'site.name',    'value' => 'My Club'],
    ['key' => 'site.tagline', 'value' => 'Together we win'],
    // Attach to a model:
    ['key' => 'color', 'value' => '#336699', 'model' => $department],
    // Delete by passing null or '':
    ['key' => 'old.key', 'value' => null],
]);

Explicit tenant ID

Useful in seeders or console commands where no Filament tenant is active:

$settings->set('welcome.text', 'Hello!', explicitTenantId: $team->id);

$settings->setMany([
    ['key' => 'foo', 'value' => 'bar'],
], explicitTenantId: $team->id);

Model-scoped bulk read

Retrieve all settings for a given key across every model of a type:

// Returns Collection keyed by model_id
$configs = $settings->getScopedConfigs('color', Department::class);
// ['1' => '#ff0000', '2' => '#336699']

Fallback chain

get() resolves settings in this order, returning the first non-null match:

1. Model-specific in current tenant (if $model is provided)
2. Tenant-wide (model_id = 0, model_type = 'system', current tenant)
3. System-wide (tenant_id = 0) — only checked when inside a tenant context

This lets you define global defaults at system level and override them per tenant or per model.

Multi-tenancy

The tenant ID is resolved automatically:

• Inside a Filament panel — uses filament()->getTenant()->getKey()
• Anywhere else — falls back to 0 (system / single-tenant)

No configuration required if you use Filament. For custom tenant resolution, extend AppSettings and override getTenantId().

Extending

class MyAppSettings extends \Agroezinger\FilamentAppSettings\AppSettings
{
    protected function getTenantId(): int
    {
        return auth()->user()?->team_id ?? 0;
    }
}

// Rebind in a ServiceProvider:
$this->app->singleton(\Agroezinger\FilamentAppSettings\AppSettings::class, fn() => new MyAppSettings());

Stored value types

value is a native JSON column. Eloquent's json cast handles encoding and decoding automatically:

Note: Avoid querying the app_settings table with raw DB::table() and ->where('value', 'some-string') — MySQL's JSON column comparison does not match SQL strings against JSON-encoded strings directly. Use the AppSettings service instead, or apply JSON_UNQUOTE(value) = ? in raw queries.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.md.