Filament System Settings Laravel Package

Getting Started

1. Install the package:

   composer require rectitude-open/filament-system-settings
   

2. Publish and run the package assets/migrations:

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

3. Register the plugin on the panel(s) that should expose the settings page, typically in app/Providers/Filament/AdminPanelProvider.php:

   ->plugin(FilamentSystemSettingsPlugin::make())
   

4. Where to look first: the "System Settings" page that appears in the panel navigation, and the settings class generated/published by the package (usually under app/Settings). That class is the contract you will read from in the rest of the app.

5. First use case: put your site name, logo/branding, contact email, and any global toggles into the settings page, then read them in a Blade layout or a service class instead of hardcoding them. This is the fastest win and validates that migrations, caching, and the Filament page wiring all work.

Implementation Patterns

• Read through the settings class, not the table. Resolve settings via the generated settings class (or its helper) in controllers, Blade, and jobs. Treating the underlying table as a query target couples your app to the package's storage schema.
• Share settings with views once. Bind commonly used values in a view composer or a small SettingsService so layouts don't each resolve settings individually. This also gives you one place to change if the package's accessor API shifts.
• Keep the plugin panel-scoped. Register it only on the admin panel (AdminPanelProvider) rather than globally, so tenant/user panels don't get an unexpected settings page. If you need per-tenant settings, that is a different design — check whether the package's storage supports a tenant key before promising it.
• Gate the page explicitly. Add the plugin/page to your authorization story (Filament policies or the page's canAccess()), because "settings" usually means secrets-adjacent data like SMTP or API keys.
• Deploy-time defaults. Seed or migrate baseline values in a seeder so fresh environments and CI have deterministic settings instead of nulls. Pair this with a deploy step that clears the settings cache.
• Testing. In feature tests, set values through the settings class (or a settings fake if the package provides one) rather than inserting rows. Assert the Filament page renders and saves with livewire()/fillForm() style tests so field renames get caught by your suite, not production.
• Extension pattern. For fields the package doesn't ship, prefer a second, app-owned settings class/page over forking the package's form schema — it survives package upgrades.

Gotchas and Tips

• v1.3.0 removed the site url field. This is the change to plan around. Anything that reads the site URL from settings — layouts building canonical links, sitemap generation, mail templates, seeded fixtures — must move to config('app.url') or your own setting. The field is gone from the form, but the corresponding column/row may still exist in the database; verify and clean it up in a migration if it's now dead weight, and remove the key from any settings seeder to avoid a stale value lingering.
• Cache invalidation is the classic failure mode. Settings are typically cached, so a value changed in the UI or in a seeder may not appear in the app until the cache is cleared. Add php artisan settings:clear-cache (or the package's equivalent) to your deploy script and remember it when debugging "the change didn't take".
• Field removals are silent breakers. A missing field won't throw at save time — it throws later when code expects the property. After upgrading, grep the codebase for the removed key and add a test that exercises the read path.
• Publishing tags drift. If you published config/migrations early, re-publish or diff them after upgrades; new releases may add keys or migrations that a stale published copy won't pick up.
• Filament version compatibility. This is a Filament plugin, so its major version is tied to the Filament major you run. Pin sensibly (^1.3 with the matching Filament constraint) and read the upgrade notes on Filament majors before bumping.
• Custom form extensions break on rename/removal. If you extended the settings form with ->form([...]) overrides or schema modifiers, re-check them after each release — they reference the package's field names directly.
• Don't store secrets you can't rotate. If you add API keys or SMTP credentials to settings, remember they live in your database and backups; prefer env/config for anything that must not be dumped, and use encrypted casts where the package/settings library allows.