Themes Laravel Package

Technical Evaluation

Architecture fit

devdojo/themes is a thin Laravel package: a service provider that registers config, publishes theme assets/views, and provides a resolution layer for swapping the active Blade theme — with the selection UI surfaced through Voyager's admin panel. As a TPM, the distinction that matters is that the durable value here is the theme resolution abstraction, not the Voyager binding. The abstraction (active theme → view path + asset path + fallback chain) is a ~200-line concern most teams would otherwise write themselves.

Fit is therefore conditional:

• Strong fit if you are already a Laravel + Blade monolith running Voyager 1.x and want an operator-facing theme picker without building one.
• Weak fit if you are not on Voyager. The package's stated scope ("Currently for Voyager") means adopting it pulls Voyager's dependency tree, maintenance posture, and Laravel version ceiling into your stack for what is otherwise a trivial view-path problem.
• Non-fit for Inertia/SPA or API-first front ends, where theme switching belongs in a build/deploy pipeline rather than runtime settings.

Integration feasibility

Mechanically straightforward: Composer install, publish config and assets, create resources/views/themes/{slug} and public/themes/{slug}, seed theme metadata, register the middleware or helper that sets the active theme. Expect a day of integration work for a developer familiar with Laravel packaging, plus design/content work to populate themes.

The friction is not installation — it is verifying the constraints. Before committing, confirm from composer.json: required PHP version, illuminate/* version range, and whether tcg/voyager is a hard require or a suggest. A hard Voyager require is the deciding factor, because Voyager's Laravel support ceiling becomes your application's upgrade ceiling.

Technical risk

The 0-dependents figure is the loudest signal: there is no ecosystem exercising this code in production, so you will be the first to hit edge cases. Budget for treating this as a vendored internal component rather than a third-party dependency.

Key questions

1. Is Voyager a hard require or suggest? Can the theme layer be used standalone?
2. What is the maximum supported Laravel/PHP version, and what is the stated policy for tracking new majors?
3. How is theme resolution implemented — View::addLocation, a custom FileViewFinder, or a middleware-driven path swap? This determines cache behavior and whether per-request (multi-tenant) theming is viable.
4. Is there a view fallback chain when a theme omits a template, or does it fail hard?
5. What is the asset pipeline assumption — Mix, plain asset(), or Vite? Does it compose with our build?
6. License terms (assumed MIT — confirm) and whether we are permitted to fork and redistribute internally.
7. What is the theme contract? Is there a manifest/schema, or is it convention-only (file naming)?
8. Who owns this internally if the upstream goes quiet — do we have a named maintainer?

Integration Approach

Stack fit

Assumes PHP 8.x, Laravel, Blade, and a server-rendered front end. It composes naturally with an existing Voyager-administered monolith. It does not compose cleanly with Vite-based asset pipelines unless the theme's asset references are rewritten at the theme contract level; the package predates and likely assumes simpler asset helpers. Verify this before scoping.

Migration path

• Greenfield: adopt directly, but fork first (see sequencing). Low cost, and you keep the option to drop Voyager later.
• Brownfield: treat as a view-extraction exercise. Move existing Blade into resources/views/themes/default/, mirror public assets into public/themes/default/, and introduce a compatibility shim — an interface your app codes against (ThemeResolver::active(), ThemeResolver::asset()) that delegates to the package when present and falls back to a hardcoded path when absent. This shim is the actual deliverable; the package becomes an implementation detail you can swap.
• Do not migrate a live application's view layer and the admin UI in the same change. Split them.

Compatibility

Establish and pin a support matrix: Laravel version × PHP version × Voyager version. Add a CI job that installs the lowest and highest supported combinations. Watch specifically for: Laravel's compiled view cache (theme switches must invalidate it), Voyager's settings-key persistence for the active theme, and published-asset overwrite semantics on vendor:publish --force.

Sequencing

1. Spike (2–3 days): throwaway branch, install, confirm the key questions above, prove theme switch end-to-end including cache invalidation.
2. Decide: adopt-as-is vs. fork-and-own vs. build-the-20%-internally. Given 0 dependents, fork-and-own is the default recommendation.
3. Fork under your namespace, add CI + a smoke test suite, pin constraints, and vendor it.
4. Define the theme contract explicitly — required views, asset manifest, config schema, fallback rules — and document it.
5. Pilot one non-critical surface (marketing pages, a low-traffic section) for one release cycle.
6. Broaden rollout; retire the shim only after the contract is proven.
7. Record the exit plan: what it costs to remove the package and Voyager together.

Operational Impact

Maintenance

Expect to own the code. Upstream activity is low and the dependent count is zero, so upstream will not surface your bugs. Budget roughly 2–5 engineer-days per year for a forked, tested copy — mostly dependency bumps and Laravel-major compatibility. The larger hidden cost is Voyager maintenance, which you inherit whether or not you use its other features.

Support

No commercial support. Community channels via DevDojo; issue throughput likely low. Requirements: a named internal owner, a written theme contract, and a documented "how to add a theme" runbook. Without those, every new theme becomes a support ticket to the platform team.

Scaling

Runtime theme resolution is cheap — config lookup plus a view path — and will not be a throughput bottleneck. Real scaling considerations:

• Per-request theming (multi-tenant): only viable if resolution is middleware-driven rather than config-driven. If it writes to config or a cached settings row, it is global-only. Confirm before designing around it.
• Cache churn: each theme switch requires a view-cache purge; frequent switching is an operational, not a compute, cost.
• Assets: themes are static files served by the web tier/CDN; scale as any static asset does. No special handling.

Failure modes

• Missing/incomplete theme directory → exceptions or unstyled pages. Mitigation: enforce a fallback chain and validate the theme contract at boot.
• Stale compiled views after switch → users see the previous theme. Mitigation: hook theme change to view:clear, or key the cache by theme.
• Published-asset overwrite on re-publish clobbers operator customizations. Mitigation: never --force in deploy pipelines; treat public/themes/* as owned content.
• Voyager upgrade changes the settings key → active theme silently resets to default.
• Composer constraint conflict blocks a Laravel security upgrade. This is the highest-severity, lowest-probability-per-incident, highest-cost failure mode — it turns a cosmetic feature into a platform upgrade blocker. Mitigation: fork with relaxed constraints, or keep Voyager strictly optional.

Ramp-up

Low for the theme consumer: a Laravel developer can author a theme in hours once the contract is documented. Moderate for the operator: whoever manages themes through Voyager needs admin-panel familiarity. The genuine ramp cost is Voyager itself — if your team does not already run it, adopting this package means onboarding an entire admin framework to gain a theme dropdown, which is a poor trade. If the team is already on Voyager, ramp-up is negligible and the package is a reasonable convenience.