Theme Bundle Laravel Package

Product Decisions This Supports

• Multi-site / white-label architecture decision: If the roadmap touches branded microsites, per-client deployments, or regional variants on one codebase, this package forces the right question early — is "theme" a first-class domain concept or a folder convention? Even without adopting it, the abstraction shape (theme registry + per-request resolver + view/asset path swapping) is a defensible answer.
• Build vs. buy for the theming layer: The capability is thin — registration, resolution, fallback, publishable assets. That thinness is itself the finding: it supports a build decision, with the package as a reference spec rather than a vendor. Budget roughly 1–3 days of a senior engineer to sketch an in-house equivalent.
• Roadmap sequencing: theming before tenancy: The package assumes theme-per-site, not tenant isolation. Adopting that assumption lets you ship simple theming first and defer the heavier tenancy work (data isolation, per-tenant queues/config) to stancl/tenancy or similar. This is a sequencing decision worth recording in the decision log.
• Delivery efficiency for agency/platform teams: "Share themes between websites" maps directly to a reusable starter-theme library. That's a repeatable-delivery lever, not just a technical nicety — it affects estimates and margin on every subsequent build.
• Rollback cost as a design input: Theme bundles tend to own directory layout and asset resolution. Recognizing that lock-in now supports choosing a decoupled abstraction (Blade namespaces + config) over a framework-opinionated one.
• Fork vs. depend (licensing): MIT means you can extract patterns or vendor code with no legal friction. This converts an adoption question into an ownership question, which is a much easier call for a PM to make.

When to Consider This Package

Consider it when:

• You genuinely operate — or have a committed roadmap for — multiple sites or brands on one application, and theme selection must happen at runtime, not build time.
• You want a cheap pressure test of your own theme abstraction before spending engineering weeks; reading the source is a low-cost design review.
• Your team is prepared to own a vendored fork. At this adoption level, that is the only realistic operating model.
• Theming needs are structural — which views, layout, and asset root a site uses — rather than visual (design tokens, dark mode, CSS variables).

Look elsewhere when:

• You have a single site. Blade namespaces plus one config flag cover it; the abstraction is pure overhead.
• The stack is API-first, Inertia, Livewire-heavy, or SPA + separate front-end. Theming there is a build-layer concern; this solves nothing.
• You need a maintained dependency. One star, zero dependents, no issue traffic, no evidence of upkeep. Do not put this on a critical path.
• You need real multi-tenancy. Data isolation, per-tenant config, queue and asset separation are out of scope — use a tenancy package and layer theming on top.
• You need design-system-level theming (tokens, per-brand CSS builds, dark mode). Front-end build concern, not this.

Critical caveat for the decision log: despite the Laravel framing in the brief, this ships as a Symfony bundle — no Laravel ServiceProvider, no facade, no config/theme.php. There is no composer require-and-go path for a Laravel app. The realistic options are (a) port the ~200 lines of registry/resolver logic, or (b) skip it. Verify this yourself before any engineering time is committed.

Verdict: Do not adopt as a dependency. Timebox a 1–3 day spike to read the source, confirm the Symfony-vs-Laravel reality, and sketch an in-house resolver. Treat any code reuse as an MIT fork under internal ownership.

How to Pitch It (Stakeholders)

For executives: This is a small, permissively licensed PHP package that handles theme switching when one application serves several branded sites. It is directly relevant to our multi-site and white-label plans, but it has essentially no adoption — one star, no dependent projects, no active maintenance — and, importantly, it is built for Symfony rather than Laravel. So this is concept value, not a vendor relationship. Recommendation: fund a short internal spike (roughly 1–3 days) to design our own small theme layer using this as a reference, rather than taking on a dependency we would have to maintain anyway. Cost is low; the risk we are avoiding is building a branded multi-site product on code nobody is keeping current. It also settles a sequencing call: ship simple theme-per-site now, defer full multi-tenancy.

For engineering: The domain model is the takeaway — a theme registry plus a resolver that swaps view paths and asset roots per request, with a default fallback, wired in through a kernel/request subscriber and a Twig-style loader path registration. Two things to verify before we spend time: this is a Symfony bundle, not a Laravel package (no service provider, no facade), and there is no compatibility pressure from dependents, so Laravel/PHP version support is unknown until you read the composer constraints. Do not add it to composer.json. Instead: skim the config tree, the registry/manager service, the kernel.request subscriber, and the compiler pass — that sequence tells you in an hour whether the implementation is thin enough to reimplement. If it is, we write ~150–200 lines of our own around Blade namespaces and config, and we own it outright.

Watch-outs to design against from day one: theme context bleeding between requests under long-lived workers/Octane; cached views compiled under one theme served to another; missing published assets after a swap; and silent fallback to the default theme masking a misconfiguration. Each is customer-visible in a white-label product and each needs an explicit test. Flag immediately if tenancy requirements start leaking into this — that is a different, much larger piece of work.