Filament Themer Luncher Laravel Package

Product Decisions This Supports

• Build vs. buy for theme operations. This package is the admin/control-center layer for Laravel Themer. It replaces the internal tooling a team would otherwise have to build for installing, activating, previewing, and troubleshooting themes — a concrete scope reduction for any roadmap item framed as "theme management UI."
• Whether to expose theme management to non-engineers. Adding Filament actions for Theme Doctor, Status Report, Debug JSON, and Explain Theme, plus health badges (healthy, dependency review, conflicts, broken parent), turns theme operations into a self-serve workflow. This is the evidence needed to decide whether marketing/ops/support can manage themes without engineering escalation, and to estimate the support-ticket reduction that justifies it.
• Risk sign-off for remote and local theme sources. The hardening in this release — HTTP timeouts and response validation, Git installs via safe process arguments instead of shell interpolation, ZIP extraction protected against absolute paths and parent-directory traversal, optional URL host allowlists, optional local path allowlists, optional backup-before-activate — is the artifact a PM takes to security review to move remote/local installs from "dev only" to "allowed in production." Without these controls, the default decision is to restrict install sources and accept the manual workflow cost.
• Incident response and SLA commitments. Health badges plus Theme Doctor and Status Report actions make theme failures triageable by first-line support rather than engineering. That directly informs on-call runbooks, escalation thresholds, and any uptime commitment that depends on theme delivery.
• Dependency and design-system governance. Ecosystem metadata visibility for requires, conflicts, provides, and design tokens supports decisions about which themes are safe to ship together and whether design tokens stay consistent across brands or tenants. This is the input for a theme compatibility policy rather than case-by-case review.
• Upgrade sequencing on the platform roadmap. The release adds Laravel Themer ^1.4, Laravel 12/13 CI coverage, and PHP 8.3–8.5 test matrix coverage. That constrains the safe window for framework and runtime upgrades and should be sequenced with the broader Laravel upgrade plan, not after it.
• QA and stakeholder sign-off workflow. Native preview compatibility with Laravel Themer 1.4 preview commands (including the --expires fix) determines whether reviewers can approve theme changes in a preview environment before activation.
• Developer onboarding velocity. Laravel Boost guidance under resources/boost/guidelines/core.blade.php is an internal enablement lever, not a customer-facing feature; value it as reduced ramp-up time, not as a product differentiator.

When to Consider This Package

Consider it when most of the following hold:

• You already run, or have committed to, Laravel Themer ^1.4 and Filament in the admin panel. The package is an extension of both; adopting it without them means adopting two dependencies at once.
• You operate multiple themes across brands, tenants, or environments, and theme switching is a runtime concern rather than a one-time static configuration.
• You want non-developers to perform theme operations — install, activate, preview, diagnose — and are prepared to grant that access with allowlists rather than open install permissions.
• You need auditability or guardrails before enabling remote installs, and the allowlist plus backup-before-activate options map to controls your security reviewers already ask for.
• Your platform is on, or moving to, Laravel 12/13 and PHP 8.3–8.5, which this release explicitly tests against.
• You want diagnostics built in rather than reconstructing theme state from logs during an incident.

Look elsewhere, or defer, when:

• You are not on Filament, or the admin surface is Inertia/Livewire custom — the value proposition is largely the Filament UI layer.
• You run a single static theme with no runtime switching; the operational surface exceeds the problem.
• You need vendor-backed support with an SLA. This is a community package; the release notes show strong CI hygiene (Pest, Pint, PHPStan, Composer validation, GitHub Actions matrix) but that is engineering discipline, not a contractual guarantee. Budget for internal ownership.
• You are air-gapped or prohibit remote fetches entirely. Even with URL host allowlists, the install path assumes network access; you would be adopting code whose headline features you must disable.
• You are unwilling to track two release cadences. Compatibility with Themer ^1.4 is explicit, so a Themer upgrade is a coordinated upgrade, not an independent one.
• Your theme layer is already solved in-house with mature runbooks; migration cost likely exceeds the diagnostics and hardening gains.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is an admin control panel for Laravel theme management that we would otherwise build ourselves. It gives non-engineers a safe way to install, preview, and activate themes, and it ships with the security controls — install allowlists, path-traversal protection, backup-before-activate — that let us permit those operations in production instead of gating them behind engineering. Net effect: less internal tooling to build and maintain, fewer theme-related escalations to engineers, and theme state that support can diagnose without a developer. Cost is low because it sits on top of libraries we already run, and it is already validated against our target Laravel and PHP versions.

To engineering: This is a thin Filament layer over Laravel Themer ^1.4 — no new persistence model to own, and it removes custom admin code from our backlog. Security posture improved materially in this release: Git installs use safe process arguments rather than shell interpolation, ZIP extraction rejects absolute paths and parent-directory traversal, remote installs have HTTP timeouts, response validation, and optional host allowlists, local symlink installs have optional path allowlists, and activation can be configured to back up first. Diagnostics are exposed as actions (Theme Doctor, Status Report, Debug JSON, Explain Theme) with health badges for dependency review, conflicts, and broken parent themes, so failures are visible rather than inferred. Two things to plan for: the ^1.4 Themer requirement means this upgrades in lockstep with Themer, and the CI matrix deliberately avoids Laravel 11 installs blocked by Composer security advisories — so do not read the matrix as an endorsement of Laravel 11.

To security and compliance: The relevant changes are the allowlist options (URL hosts, local paths), the removal of shell interpolation from Git installs, ZIP extraction hardening against path traversal, HTTP timeout and response validation on remote fetches, and optional backup-before-activate. These are the controls to evaluate against our install policy; enabling remote installs without allowlists configured would leave the intended protection unused.

Known limits to state up front: no vendor SLA; requires both Filament and Laravel Themer; adds a dependency to the upgrade graph; and the preview/activation paths are tied to Themer 1.4 semantics, so version drift is a real operational risk rather than a theoretical one.