Themevel Laravel Package

Technical Evaluation

Architecture fit Themevel is a presentation-layer package: a Laravel service provider that registers a theme resolver, overlays theme view paths onto the framework's view finder (with fallback to base resources/views), and resolves theme asset URLs. It has essentially no coupling to domain code — controllers keep returning view names, and the package decides where to look. That makes it a good fit for:

• Server-rendered Blade applications with white-label or per-tenant branding.
• Products where "theme" is a genuine product surface (customer portals, CMS-lite, multi-brand marketing sites).
• Teams that want a small, single-purpose dependency rather than a full CMS.

It is a poor fit if the front end is Inertia/React/Vue/Livewire-heavy, or if theming is really just "a few CSS variables." In those cases the package adds an indirection layer without buying view/asset resolution.

Integration feasibility Low-friction to spike: composer require shipu/themevel, publish config and assets, register the provider (auto-discovery on modern Laravel), set default_theme and theme path. A working two-theme proof of concept is a 1–3 day exercise for one engineer. The real work is not installation — it is the fallback chain, asset pipeline (Vite/Mix manifest per theme), and per-request theme selection if multi-tenant.

Technical risk

• Maintenance risk dominates. 345 stars, a single maintainer, last release August 2023, and CC0-1.0 licensing. CC0 is maximally permissive (good for forking and vendoring) but signals no commercial support path and no warranty. Assume you own the code the day you adopt it.
• Framework drift. The package depends on Laravel view-finder and asset-publishing internals. Verify composer.json constraints against our target Laravel/PHP versions before committing; Laravel 11/12 and PHP 8.3+ support is the first thing to test.
• State safety under Octane/queues. Theme is effectively ambient request state. Long-lived workers must reset it per request or themes will bleed between tenants. This is the highest-severity correctness risk.
• Trust boundary. If themes are customer- or third-party-authored, they contain Blade (executable PHP). Treat theme upload as code deployment, not content upload.
• Caching interaction. view:cache, config:cache, and per-theme compiled views need an explicit invalidation story.

Key questions

1. Is the front end Blade-first, or is this solving a problem we don't have?
2. Are themes internal-only or customer-authored? (Drives sandboxing and review workflow.)
3. Do we need per-request/per-tenant theme switching, or a single global theme?
4. What Laravel/PHP versions must we support, and does the package clear that bar today?
5. Are we willing to fork and own it? Who is the named owner?
6. How do per-theme assets work with our Vite build and CDN strategy?

Integration Approach

Stack fit Target a Laravel monolith or modular monolith on Blade, PHP 8.1–8.3, with Vite for assets. Themevel covers view resolution natively; asset resolution will need a thin adapter so each theme's Vite manifest is resolved correctly rather than relying on the package's default asset URL helper.

Migration path Adopt incrementally and behind an abstraction:

• Wrap the package's theme facade in our own ThemeResolver contract (activate, current, asset, fallback). Nothing in application code calls the vendor API directly.
• Start with 2–3 internally authored themes and a config-driven theme registry — no database-backed theme CRUD in phase one.
• Move one surface at a time: marketing/tenant portal first, authenticated app shell second.
• If the package later stalls, the wrapper lets us swap to an in-house resolver or a fork with a contained diff.

Compatibility Pin the Laravel minor version, add the package to the upgrade test matrix, and assert behavior for: missing theme fallback, view:cache rebuild, config:cache after adding a theme, and Octane request isolation. Confirm asset publishing works non-interactively in CI (vendor:publish --force in the deploy step, or committed theme assets).

Sequencing

1. Week 1 — ADR plus spike: install, two themes, measure view/asset resolution, confirm version support, decide build-vs-buy.
2. Week 2 — ThemeResolver wrapper, fallback chain, per-theme asset adapter, CI asset publish.
3. Week 3 — Pilot on one low-risk surface; add Octane reset middleware and cache-invalidation hooks.
4. Week 4 — Hardening: path-traversal guards on theme names, theme skeleton template, runbook, docs.
5. Later — Only then consider DB-backed theme selection and customer-authored themes.

Operational Impact

Maintenance Budget roughly 0.1 FTE of ongoing ownership, concentrated around Laravel upgrades. Practically: fork to our org (CC0 permits it), vendor the fork in Composer via VCS, and keep our patches minimal and documented. Track upstream releases; expect few.

Support Community-only, no SLA, no vendor to escalate to. That is acceptable for a presentation-layer package but not for anything on the critical path without an internal owner and runbook. Document the fork point and the upgrade procedure explicitly.

Scaling Runtime cost is negligible — theme resolution is a path lookup and a view-finder entry. Real scaling considerations are: N themes × compiled Blade views in cache, duplicated per-theme asset bundles, and CDN path prefixes per theme. Add a per-theme asset prefix to keep cache keys clean. Under Octane, enforce a theme reset at request start and in queued jobs.

Failure modes

• Missing/misnamed theme → blank page or 500; mitigate with explicit fallback to a known-good default and a health check.
• Missing assets after deploy → broken layouts; mitigate by publishing theme assets as a deploy gate.
• Stale config:cache after a theme is added → theme invisible in production only.
• view:cache not cleared on theme change → mixed output between tenants.
• Theme leakage across requests under Octane → cross-tenant data exposure. Highest severity; test explicitly.
• Path traversal if theme identifiers are user-supplied → arbitrary file inclusion.

Ramp-up Low for anyone fluent in Blade — about a day to be productive, with most of that spent on our wrapper and asset conventions rather than the package itself. Documentation upstream is thin, so plan to write a one-page internal guide plus a checked-in example theme skeleton. The learning curve is not the package; it is our fallback, caching, and asset conventions layered on top.