Pug Filter Markdown Laravel Package

Technical Evaluation

Architecture fit This package is a Laravel view-layer adapter: it registers a service provider, binds a view engine for a non-Blade file extension (.pug), and delegates compilation to pug-php. Architecturally it sits on a stable Laravel extension point (view engine resolution + compiler/cache path), so it does not fight the framework. It coexists with Blade rather than replacing it, which keeps the blast radius small.

The 1.2.0 change — "Pug-php 3 compatibility" — is nominally a minor release on this package, but it is a major upstream dependency move (pug-php 2.x → 3.x). TPM framing: treat this as a dependency-line migration, not a feature update.

Integration feasibility Low for greenfield: composer require, publish config, point a view namespace at .pug files. The real feasibility question is brownfield — any app already pinning pug-php 2.x, or any other package that co-depends on it, now has a constraint to reconcile.

Technical risk

• PHP version floor — pug-php 3 raises the minimum PHP version; this can silently raise our effective floor and block upgrades elsewhere. Must be confirmed against our supported matrix.
• Upstream compiler rewrite — the 3.x line is built on a reworked compiler with a different extension/filter registration API. Custom filters, keywords, or options our templates rely on may need rewrites.
• Transitive churn — 3.x pulls a different dependency set; conflict surface with existing packages is non-trivial and only visible at composer update.
• Output fidelity — whitespace, escaping, and attribute-rendering behavior can shift between compiler majors. Rendered HTML diffs are plausible even where templates compile.
• Caching semantics — compiled-template cache keys/format may change; stale cache after deploy is a realistic (and confusing) failure mode.
• Risk rating: medium. Not a drop-in patch, but contained to the view layer if we isolate it.

Key questions

1. What is the exact PHP minimum for this package at 1.2.0 and for pug-php ^3?
2. Which upstream compiler line does 3.x target, and which extension/filter APIs changed?
3. Does 1.2.0 still permit pug-php 2.x (dual constraint), or is it a hard bump?
4. Is this a breaking change for consumers, or does the package version it as compatible?
5. What is the maintenance status and security posture of pug-php 3.x?
6. Are there published breaking-change notes for the 2.x → 3.x compiler move?
7. Do we have a template regression suite, or do we need to build one before migrating?

Integration Approach

Stack fit Fits cleanly as a secondary view engine alongside Blade. Recommended posture: Pug for static/markup-heavy partials, Blade for anything needing Laravel directive ergonomics (@auth, @csrf, components). Avoid a wholesale view-layer migration; mixed rendering is the low-risk position.

Migration path

1. Baseline current rendering — snapshot HTML output of every Pug template on the existing pin.
2. Branch-isolate the upgrade: bump this package to 1.2.0 and pug-php to ^3 in one commit; resolve conflicts there, never on the mainline.
3. Diff rendered output against baseline; triage as cosmetic vs. functional.
4. Migrate custom filters/keywords to the 3.x registration API.
5. Clear and rebuild the compiled-template cache as an explicit deploy step.

Compatibility

• Verify Laravel version constraints for 1.2.0 before assuming it fits our current framework minor.
• Check for co-dependents on pug-php — a shared transitive dependency is the most likely source of a blocked upgrade.
• Confirm CI matrix includes the raised PHP floor, or the first signal we get is a runtime failure.
• Any Blade-only fallback path should be validated so we can retreat without a revert-the-release scenario.

Sequencing Dependency audit → PHP/Laravel matrix confirmation → branch upgrade + template snapshot diff → filter/keyword migration → cache-rebuild deploy step → staged rollout behind a feature flag if Pug is on a user-facing critical path. Do not bundle this with an unrelated framework or PHP upgrade; keep the failure signal attributable.

Operational Impact

Maintenance Ongoing cost is the Pug toolchain, not this wrapper — the wrapper is thin and likely low-churn. Track three things: pug-php 3.x security advisories, the wrapper's responsiveness to upstream breaks, and our own fork of any custom filters. A thin wrapper over a major-versioned compiler means upstream breaking changes reach us with limited buffering.

Support Template-level errors surface as render-time exceptions, which are less obvious to diagnose than Blade compile errors. Support burden concentrates on whoever owns templates; document the compile-error → cache-clear → retry playbook. Team familiarity with Pug syntax vs. Blade is a real ramp cost and a hiring/support consideration.

Scaling Compilation is cached after first render, so steady-state cost is I/O on compiled templates, not parsing. Watch: writable cache path on every app node (multi-node deployments need shared or per-node warm cache), cold-cache latency after deploys, and opcache interaction with regenerated files. Validate behavior under horizontal scale before assuming parity with Blade.

Failure modes

• Compile error in one template → hard failure of that view (and any view including it), at request time.
• Stale compiled cache post-deploy → old markup served with no error signal.
• Dependency conflict → upgrade blocked, discovered late at composer update.
• Missing PHP extension or raised floor → runtime failure on a subset of environments only.
• Escaping/whitespace drift from the compiler major → silent, reviewable-only-in-diff correctness regressions.
• Mitigation for all of the above: template regression snapshots in CI plus an explicit cache-rebuild deploy step.

Ramp-up Low-to-moderate. The wrapper is simple; Pug itself is the learning curve. Budget for one owner to absorb the 3.x filter/keyword API, produce a short internal template-conventions doc, and stand up the rendering-snapshot harness. That harness is the single highest-leverage deliverable here — without it, the 2.x → 3.x move is unverifiable and every future upstream bump stays expensive.