Filament Palette Laravel Package

Getting Started

• Install with composer require octopyid/filament-palette, then publish the config with php artisan vendor:publish --tag="filament-palette-config" (check the package README for the exact tag; the config file is the first place to look after install).
• Register the plugin on the panel(s) you want the switcher on, in your PanelProvider's panel() method, then run php artisan filament:optimize / clear caches if the switcher doesn't appear.
• Open config/filament-palette.php immediately. As of v1.1.0 this file contains the new cache_store key (env: FILAMENT_PALETTE_CACHE_STORE), which controls where the selected palette is persisted. Leave it null to inherit the app's default store unless you have a reason not to.
• First use case: drop the switcher into a panel so end users can pick a palette/theme and have it survive page navigation and re-login. Verify it works by switching palettes, hard-refreshing, and confirming the choice sticks — that single loop exercises the plugin, the config, and the cache plumbing at once.

Implementation Patterns

• Register per panel, not globally. Because the switcher is a Filament plugin, add it only to the panels that should expose theme switching (e.g. the admin panel, but not a customer-facing panel with a locked brand). This keeps the cache keys and UI surface scoped.
• Pick an explicit cache store in multi-tenant or multi-app setups. If several apps share a Redis instance, set FILAMENT_PALETTE_CACHE_STORE (or the config key) per app so palette entries don't collide across environments. Pair this with a prefix-aware store rather than relying on the default.
• Lean on the new local fallback for development ergonomics. With CACHE_STORE=array (a common local default in Laravel 11+ skeletons), v1.1.0 transparently falls back to the file driver in local so palette choices persist while you click around. Don't fight it — but do understand it means your local behaviour differs from production, so sanity-check persistence in a staging environment that uses the real store.
• Config-driven, not code-driven. Prefer flipping the env var over editing the published config, so deploys and container images stay identical. Run php artisan config:cache as part of your deploy and re-run it whenever the env value changes.
• Testing your own integration. Set the palette cache store to array in phpunit.xml/pest.php so tests don't bleed palette state between cases; assert on the rendered switcher rather than on cache internals to keep tests resilient to package refactors like the PaletteManager rewrite in 1.1.0.
• Integration with Filament theming. Treat the palette selection as user preference state: read it where you build dynamic CSS/theme injection, and consider coupling it to a user profile column if you need selections to survive a cache flush.

Gotchas and Tips

• The file fallback is local-only. In production with CACHE_STORE=array or null, selections will not persist. If users report "my theme resets on every request", check APP_ENV and the configured store first — this is the single most likely support issue after upgrading.
• Ephemeral drivers hide bugs locally. Because v1.1.0 masks array/null drivers in local dev, a misconfigured production cache store won't reproduce on your machine. Add a staging smoke test that switches a palette and reloads.
• Cache is not a database. php artisan cache:clear, a Redis eviction, or a store migration will silently reset everyone's palette. If palette choice is a user-facing preference, mirror it to the users table and treat the cache as a fast path.
• config:cache staleness. Changing FILAMENT_PALETTE_CACHE_STORE without re-caching config leaves the old store in play. Make config:cache part of the deploy script, and verify with php artisan tinker that the resolved config value matches expectations.
• Upgrading from 1.0.x is low-risk but not zero-config. The PaletteManager was refactored; if you decorated, extended, or type-hinted against its internals, re-check your code. Publish/merge the config file again to pick up the new cache_store key — existing published configs won't have it.
• No composer.lock and .gitattributes exclusions are intentional. Don't expect vendor/octopyid/filament-palette/tests to exist in your install; if you were reading package tests for usage examples, pull the repo separately. Also pin the package version in your own composer.lock as usual — upstream no longer ships one, which is correct but means you're solely responsible for reproducible installs.
• Extension point: if the built-in store resolution doesn't fit (e.g. you want per-user cache keys or a database store), bind your own implementation against the package's manager contract in a service provider rather than editing published config, so future releases stay upgradeable.
• CI signals: v1.1.0 adds Pest + Orchestra Testbench coverage across PHP 8.2–8.4. If you're on PHP 8.1, you're outside the tested matrix — verify manually or upgrade before filing issues.