Filament Settings Hub Kaido Laravel Package

Getting Started

Where to look first. The repo now has a real release history (v4.2.5 → v5.0.0), so the changelog and diff are legitimate first-class documentation alongside the source. Read in this order:

1. CHANGELOG.md / GitHub releases — v5.0.0 is a major bump for what reads like a cosmetic + publishing change, so confirm nothing in the diff is silently breaking.
2. config/ — published config tells you table names, cache key prefix, and how settings groups are resolved.
3. database/migrations/ — storage model (key/value table vs. JSON column per group) and, given v5 touched "migration publish logic," the exact filename/timestamp of the migration stub.
4. src/ for the service provider, any SettingsPage/SettingsResource classes, and the helper (src/helpers.php or a Facade) that exposes the getter used in views.
5. resources/views/ — v5.0.0 changed dark theme styling here; this is now a real surface you may want to override.
6. src/Filament/ for the page registration contract — what you hook into your panel provider.

Minimal setup.

composer require juniyasyos/filament-settings-hub-kaido:^5.0
php artisan vendor:publish --provider="Juniyasyos\FilamentSettingsHub\FilamentSettingsHubServiceProvider"
php artisan migrate

Run the publish step interactively (php artisan vendor:publish with no flags) and read the tag list. v5 reworked the migration publish logic, so the tag names or which assets ship by default may differ from anything you read on a blog. Then publish migrations explicitly with --tag=.

Register the plugin on the panel you want the UI on:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(\Juniyasyos\FilamentSettingsHub\FilamentSettingsHubPlugin::make())
        // ...
}

Verify the exact namespace and plugin class name against src/ — forks of this kind of package rename the namespace, so copy it from the service provider rather than from a blog post.

First use case. Pick the lowest-risk, highest-value setting: a site name, support email, or a feature toggle. Create the settings group through the Filament UI, add the field, save, then read it back in a Blade view or Livewire component via the package helper — in both light and dark mode, since that is what v5 changed.

Implementation Patterns

Group-per-domain, not one giant form. Treat each settings page as a bounded context: general, mail, integrations, billing. Small groups mean small forms, fast saves, and a cache key you can invalidate surgically. A single 80-field settings page produces slow ->save() calls and unusable validation errors.

Read through the helper, write through the UI. Resist calling the settings model directly from application code. Use the package accessor (settings('mail.from_address') or the Facade — confirm the shape in src/helpers.php) so whatever caching layer ships with the package stays in effect. Direct Eloquent reads bypass the cache and silently drift from what the admin sees.

Bind settings to form defaults. The highest-leverage integration is seeding Filament form defaults from stored settings rather than hardcoding them:

TextInput::make('from_address')
    ->default(fn () => settings('mail.from_address', config('mail.from.address')))

Always supply the config fallback as the second argument. On a fresh install, or after a rollback, the setting row may not exist yet and an unguarded helper call throws inside the form render.

Feature flags as a workflow. Store booleans in a features group and gate navigation and actions:

->visible(fn () => (bool) settings('features.beta_reports', false))

Because settings are cached per-request this is cheap in visible() closures, but do not call it inside a loop over hundreds of rows unless you confirm the package memoizes.

Environment-aware bootstrap. Keep secrets out of the database UI. Store the non-secret parts of a config (host, port, from-name) as settings, and inject the credential from env(). A settings hub that writes API keys to a table is a compliance problem the moment the DB is dumped.

Test with a known state. In feature tests, set settings explicitly in setUp() rather than relying on seeded defaults, and clear the settings cache in tearDown(). Packages of this maturity commonly cache to the Laravel cache store, so a stale entry from one test leaks into the next under RefreshDatabase.

Theming is now a supported seam. With v5.0.0 reworking dark theme styling, the intended extension point for visual changes is publishing the package views into resources/views/vendor/... and editing the copy — not patching vendor/. If you have brand-specific panel styling, diff the shipped views against your overrides on every bump.

Gotchas and Tips

v5.0.0 is a major bump — read the diff before adopting. The release note mentions only dark theme styling and migration publish logic, which sounds patch-level. The version number says otherwise. Skim the v4.2.5...v5.0.0 compare on GitHub for renames, removed methods, or changed namespaces before you trade a working install for it.

Re-publishing migrations can produce a duplicate timestamp. If v5's updated "migration publish logic" changed the migration stub's filename timestamp, a previously published migration and the new one will both exist and php artisan migrate will attempt to create the table twice. Delete the old published migration deliberately (it is already recorded in the migrations table), or verify the up() has an if (! Schema::hasTable(...)) guard. Do not blanket --force publish on a database you care about.

The cache is the number one debugging trap. Most settings hubs write to the DB and then invalidate a cache key. If you edited a row by hand, or restored a production dump locally, the app keeps serving the old value. When a saved setting "doesn't take effect," run php artisan cache:clear (and config:clear) before you start reading source code.

Publish tags are not standardized — and just moved. Run vendor:publish interactively, read the tag list, then re-run with --tag= per asset. Because v5 altered publish logic, do not assume the tag you used on v4 still exists.

Stale published views survive the upgrade. If you published views under v4, upgrading to v5 leaves your old copies in place and you will never see the new dark theme styling. Either re-publish with --force and re-apply your customizations, or restore the override deliberately.

Permission gating is your responsibility. Filament plugins register pages; they generally don't ship policies. Wire the settings page into your existing role model with ->authorize() or a canAccessPanel() check, otherwise every panel user can rewrite your mail credentials.

Pin the version, and treat upgrades as reviewed code. There is a release history but still negligible third-party pressure on the upgrade path. Use an explicit constraint ("^5.0", not "*"), commit the lockfile, and read the diff before bumping. Budget for the possibility that you are the maintainer of your own fork.

Type coercion bites on booleans and arrays. Filament toggles return true/false, but a value read back from the DB or .env may be the string "0". Normalize at the boundary — filter_var($value, FILTER_VALIDATE_BOOLEAN) — instead of trusting truthiness in a Blade @if.

Extension points to keep in mind. The service provider is the registry for custom settings pages, so subclassing the base page and registering your own class is cleaner than editing published views. If the package exposes a Settings contract or abstract class, implement it per group so your groups are autocompleted and statically analyzable rather than string-keyed.

File uploads need a disk decision. If a settings field is a FileUpload, confirm which disk and visibility it defaults to. Logos stored on local will 404 in production behind a CDN; set ->disk('public')->visibility('public') explicitly.