Filament Themer Luncher Laravel Package

Getting Started

1. Install the package with Composer alongside Laravel Themer ^1.4 — the Luncher is a Filament plugin, so it needs a working Laravel Themer install and a Filament panel already registered:

   composer require filament-themer-luncher
   

   The release targets Laravel 12/13 and PHP 8.3–8.5; if you are still on Laravel 11, expect Composer to pull older versions or block the install entirely due to security advisories on the 11 branch.

2. Register the plugin on your panel provider (->plugin(FilamentThemerLuncherPlugin::make()) — check the README for the exact namespace and any ->navigationGroup()/->authorize() chaining you want).

3. Publish and review config before first use — specifically the new install allowlists (allowed_remote_hosts, local path allowlist) and the backup-before-activate flag. Defaults are secure but restrictive; a remote install will fail until you add the host.

4. Where to look first: the Luncher's theme list page. Each row carries the v1.1 health badges (healthy, dependency review, conflicts, broken parent), which is the fastest way to see whether an existing theme is usable before you touch anything.

5. First real use case: open an existing theme and run the Theme Doctor action. It surfaces requires, conflicts, provides, and token metadata in one pass — this is the diagnostic you'll return to whenever a theme misbehaves after a Laravel Themer upgrade.

Implementation Patterns

• Pre-flight every theme change with Theme Doctor. Wire it into your workflow rather than treating it as a debugging-only tool: run Doctor → read Status Report → only then activate. Doing this consistently catches broken parent themes and unmet requires before they hit a staging deploy.
• Use health badges as a dashboard, not a gate. Render the Luncher page as a monitoring view for a multi-theme install (one theme per tenant/brand). The conflict and broken-parent badges give you an at-a-glance triage list across all registered themes.
• Explain Theme for onboarding. The Explain Theme action is the quickest way to give a new team member context on an unfamiliar theme — better than reading its manifest by hand.
• Preview before activate. Laravel Themer 1.4 previews now use --expires; the Luncher passes this through natively. For any client-facing theme, preview with a short expiry, confirm, then activate — ideally with backup-before-activate enabled so a bad activation is a one-command rollback.
• Prefer theme:refresh-aware cache invalidation. The Luncher now prefers theme:refresh when the command exists. If you have custom cache-busting logic, hook it to the same signal instead of duplicating it — otherwise you'll get stale token/health data after an install.
• Lock down installs in production. Configure the remote URL host allowlist and, if you allow symlinked local themes, the local path allowlist. Treat these as environment-specific config values (permissive in local, tight in production) rather than global defaults.
• Boost guidance is a hint, not docs. The resources/boost/guidelines/core.blade.php guidance helps AI assistants and IDE tooling; keep it in sync if you fork or extend the plugin.

Gotchas and Tips

• Allowlists are opt-in and silent-ish on failure. A remote install from an unlisted host will be rejected. If an install "just doesn't work," check the URL host allowlist before anything else.
• Git installs now use safe process args, not a shell string. Any custom clone flags or post-clone shell tricks you were relying on via interpolation won't work — pass them through the supported configuration instead.
• ZIP extraction rejects absolute paths and ../ traversal. Legitimate archives that include parent-directory entries (some build tools produce them) will now fail. Re-pack the theme ZIP flat before importing.
• Preview links expire. The --expires fix means previews are time-boxed by design — don't share a preview URL as if it were permanent. Regenerate for each review round.
• Activation with empty/deactivation-style arguments is now handled, so conditional code that called activate with a null theme will no longer blow up — but double-check any wrapper you built around the old behaviour.
• Backup-before-activate is protection, not a backup strategy. It covers the activation step only; it is not a substitute for backing up theme files before manual edits.
• Remote installs have HTTP timeouts. Large themes over slow links may need a longer timeout configured; failures surface as validation errors, not silent hangs.
• Health badges can flag "dependency review" on themes that are fine — it means metadata suggests a review, not that the theme is broken. Read the Status Report before acting.
• Debug JSON is your escalation path. When a badge or Doctor result is ambiguous, grab the Debug JSON — it's the most compact artifact for a bug report or for diffing before/after an upgrade.
• CI matrix note for contributors: Laravel 11 jobs were removed deliberately. Don't re-add them in a PR — Composer will refuse the install.