Blade Laravel Package

Technical Evaluation

What this package is. surgiie/blade extends Laravel's Blade compiler so it can render arbitrary text, not just view files served through Laravel's view layer. That places it in the same category as standalone-Blade adapters (e.g. jenssegers/blade): it decouples the compiler from the framework's ViewFactory so a script, CLI tool, queue worker, or non-Laravel PHP service can render templates.

Architecture fit.

• Good fit if we have a concrete non-view templating need: transactional email/notification bodies rendered outside the HTTP view stack, code or config generation, document/PDF text assembly, prompt templates, log/alert formatting. Blade's directive syntax is already known to our Laravel engineers, so the syntax cost is near zero.
• Poor fit if the only requirement is normal HTML views inside a running Laravel app — core Blade already does that, and adding a second compiler is pure surface area for no gain.
• The package is only justified if it offers something upstream Blade and existing standalone wrappers don't: a genuinely framework-free compile path, multi-driver template loading, per-render cache isolation, or support for text (non-HTML) escaping semantics.

Integration feasibility. Composer-installable PHP library, so mechanically trivial. The real feasibility question is dependency constraints:

• Which illuminate/* packages and version ranges does it require? If it pins illuminate/view to an older major, it will collide with our app's Laravel version and composer update will fail or, worse, silently downgrade shared components.
• Does it hard-fork the compiler (copied BladeCompiler/Concerns\Compiles* traits) or wrap illuminate/view? A copied compiler means we inherit a snapshot of Blade that will drift from upstream on every Laravel release.
• PHP version support (8.1–8.4), autoload style, presence of a service provider/facade, and whether any Composer scripts run at install time.

Technical risk. Treat this as unvetted third-party code until proven otherwise: zero stars and zero dependents mean no community scrutiny, no downstream bug reports, and no realistic chance a CVE in this package gets flagged by scanners. Named risks:

• Bus factor / abandonment. Likely single maintainer, low release cadence. If it stops tracking Laravel, we either fork it or rip it out.
• Escaping and safety semantics. {!! !!} vs {{ }} behavior, directive handling, and @include path resolution are a security surface. Any divergence from upstream Blade's default-escape behavior is an XSS risk the moment template content is user-influenced.
• Compiled-template cache. Standalone Blade writes compiled PHP to disk. An attacker-writable or web-reachable cache directory is a code-execution path; a misconfigured one is a stale-output path.
• Supply chain. No dependents means no ecosystem pressure to audit it; we must read the source ourselves.
• License compatibility with our distribution model is unconfirmed.

Key questions to answer before any code is written.

1. Is it a fork, a wrapper, or a rewrite of illuminate/view? How does it track upstream Blade between Laravel majors?
2. What is the license, and who maintains it? Commit history, release cadence, issue responsiveness.
3. Is there a test suite and CI, and does it include parity tests against upstream Blade output?
4. Which Blade features survive: components and slots, anonymous components, @include/@extends/@section, custom directives, Blade::if, stacks?
5. Exact Composer constraints on illuminate/* and PHP; does it install cleanly alongside our current Laravel major?
6. Where does it write compiled templates, how is the cache invalidated, and can the path be locked down?
7. Is default escaping identical to upstream? Any directive that emits raw output by default?
8. What does it do that jenssegers/blade or a 50-line wrapper around illuminate/view does not?

Integration Approach

Stack fit. Two distinct scenarios, different answers:

• Inside an existing Laravel app: low fit. We already have Blade. Adopt only for a bounded, non-view rendering need, and only if it beats a thin internal wrapper over Illuminate\View.
• In a non-Laravel PHP service or CLI: this is the actual use case, and the package's value is highest there. Validate it in that context first, not in the monolith.

Migration path (parity-first, reversible).

1. Due diligence gate (½–1 day). Read composer.json and the compiler source. Confirm fork-vs-wrapper, license, test coverage, and escaping behavior. Kill the initiative here if constraints conflict with our Laravel major.
2. Spike (1–2 days). Install in a throwaway branch. Render 5–10 real templates we already produce — a notification email, a generated config file, a PDF body — and diff output against the current renderer byte-for-byte where feasible.
3. Adapter layer. Put the package behind our own small interface (TemplateRenderer::render(string $name, array $data)). Nothing in application code imports Surgiie\Blade directly. This is the swap-out insurance that makes the abandonment risk cheap.
4. Single-surface rollout. Enable for one use case behind a feature flag — preferably a low-blast-radius one like CLI scaffolding or internal email — with dual-run comparison in staging.
5. Widen only after a full release cycle of clean output and no upstream breakage.

Compatibility.

• Pin an explicit version range; do not float.
• Run composer why-not / composer update --dry-run against the main branch before committing.
• Add the package to Dependabot/Renovate and composer audit in CI so a future advisory (however unlikely) surfaces.
• Test on every Laravel major upgrade: diff the package's compiler against the new illuminate/view compiler and record the gaps.

Sequencing. Due diligence → spike → adapter → one surfaced use case → monitoring → widen. Do not start with "replace our view layer"; that inverts the risk profile and is almost never the right call.

Operational Impact

Maintenance. Assume we become the maintainer. With no dependents and no visible community, there is no one else to file the bug or ship the patch. Budget a recurring line item: review the package against each Laravel release, patch or vendor the source if it drifts. Confirm up front that we can legally vendor the source into our repo — that is the difference between "annoying" and "blocked" if the maintainer disappears.

Support. No vendor, no community, no Stack Overflow corpus. Support is entirely internal. Require at least two engineers who can read compiled PHP and debug a template-cache problem, so we are not single-threaded on one person's knowledge.

Scaling. Rendering itself is cheap: compile once, cache the compiled PHP, execute on subsequent renders. The scaling concerns are operational, not throughput:

• Cold-start storms. On container deploys, every pod compiles the same templates on first render. Warm the cache during build/deploy and make the compiled path read-only at runtime where possible.
• Shared cache directory. Multi-pod setups need either per-pod ephemeral caches (simple, slight duplicate work) or a shared volume (faster, but introduces locking and staleness). Pick deliberately.
• Cache invalidation. Key compiled artifacts on source mtime/hash. Deploy-time staleness is the most likely production incident with any Blade-derived renderer.

Failure modes to instrument and alert on.

• Cache directory unwritable or full → hard render failure, often only on the first request after a deploy.
• Stale compiled template after a deploy → wrong content shipped, silently, with no error.
• Upstream-incompatible release pulled in by a floating constraint → fatal at autoload or render time.
• Unescaped output path → XSS or injected content where templates touch user data.
• Template name path traversal if the loader accepts user-supplied names.
• Abandonment: package no longer installable against a future Laravel/PHP version.

Ramp-up. Low. Anyone who knows Blade knows the syntax on day one; the learning curve is entirely "where do templates live, where does the compiled cache go, how is it invalidated" — roughly half a day for a Laravel-fluent engineer. The expensive knowledge is the failure modes above, and that has to be written into a runbook, because it will not be found in the package's documentation.

TPM recommendation. Given zero stars and zero dependents, default to no-go unless the spike proves a capability we cannot get from jenssegers/blade or a ~50-line wrapper around illuminate/view. If adopted, constrain it behind an internal adapter, one use case, pinned versions, and an explicit "we may have to fork this" line item in the plan.