Parser Laravel Package

Technical Evaluation

Architecture fit

phug/parser is not a standalone solution — it is one node in the Phug Pug/Jade toolchain (lexer → parser → AST → compiler → renderer → formatter). A Laravel team that installs only phug/parser gets an AST builder with no render path, no view integration, and no cache layer. The architecturally correct dependency is the phug/phug meta-package (or at minimum phug/renderer), with phug/parser treated as a transitive detail. Any design that names phug/parser directly in composer.json should be treated as a smell.

Fit is narrow but legitimate: Laravel's view layer is pluggable, and Pug's indentation-based syntax is genuinely attractive for design-heavy marketing pages, transactional email HTML, and static-style content where Blade's @directive noise degrades designer ergonomics. It is a poor fit for application UI, Livewire/Inertia surfaces, or anything where Blade component semantics and Laravel's first-party tooling (view caching, @vite, Blade components) are load-bearing.

Integration feasibility

Technically straightforward: Composer install, PHP 8.x, an Illuminate\View\Engines\EngineInterface implementation registered via a service provider, and a custom view finder for .pug extensions. Coexistence with Blade is achievable by scoping Pug to a separate view namespace (e.g. resources/views/pug/) rather than swapping the default engine — this keeps blast radius contained and avoids a flag-day migration.

The real feasibility risk is the ecosystem gap, not the code. With 4 stars and 0 dependents, there is no evidence of production Laravel usage to borrow from: no maintained first-party Laravel bridge in this metadata, no community integration patterns, no known-good service provider to copy. We would be writing and owning the Laravel glue ourselves, and that glue is where 80% of the operational cost will live.

Technical risk

• Bus factor: a single-maintainer ecosystem with negligible community surface. If upstream stalls, we fork or we migrate off — both are real costs.
• Repo/package mismatch: the supplied repository (phug-php/reader) does not correspond to the package identity (phug/parser). This must be resolved before any dependency audit; an incorrect or renamed source of truth is a supply-chain question, not a clerical one.
• Expression evaluation: Pug permits arbitrary PHP expressions inside templates. Untrusted or user-editable templates become remote code execution. Template authorship must be restricted to the trusted codebase and reviewed in PR like any source file.
• Silent divergence: a parser/compiler version bump can change output HTML without a runtime error. Without golden-file snapshot tests, this surfaces in production.
• Adoption signal is the headline risk. 4 stars, 0 dependents, opportunity score 23.12. This is a low-value, low-leverage component in a market where Blade, Twig, and Antlers are entrenched. We would be taking on a niche dependency for a cosmetic developer-experience gain.

Key questions

1. What problem is Pug actually solving here — designer handoff, markup conciseness, or a specific existing template corpus? If there is no existing Pug corpus, the case collapses.
2. Why is phug/parser named rather than phug/phug? Is this a deliberate slice or a misidentified dependency?
3. Which repo is authoritative for the package — phug-php/reader or a phug-php/parser repo? Who controls it?
4. Supported PHP and Laravel versions, and is there a tested matrix?
5. Where does the compiled-template cache live, and is it shared across web/queue/CLI containers and deploy slots?
6. Who owns the Laravel view-engine adapter internally, and what is the exit cost if we abandon it in 12 months?

Integration Approach

Stack fit

Assume Laravel 10/11/12 on PHP 8.2+. Pug should be introduced as a secondary engine behind an isolated view namespace, never as the default. Blade remains the engine for all application UI; Pug is confined to a defined content class (marketing pages, email templates). This preserves first-party tooling and keeps the decision reversible.

Migration path

Do not migrate existing Blade views. There is no incremental Blade→Pug path, and rewriting working views to a 4-star dependency inverts the risk/reward. Instead:

1. Vendor and pin phug/phug (not phug/parser) with an exact version constraint, committed composer.lock, and a documented upgrade procedure.
2. Build the adapter in-house: view engine, finder, service provider, config (cache path, enabled namespaces), and a view:clear-equivalent for the Phug cache.
3. Pilot with 3–5 net-new templates in the least-coupled surface available — transactional email HTML is the strongest candidate (no JS, no Blade component dependency, no Livewire interaction, deterministic output, easy snapshot testing).
4. Expand only if the pilot clears the exit criteria below.

Compatibility

• Verify PHP 8.2/8.3 support explicitly; the metadata's recent release date suggests activity but does not confirm a CI matrix.
• Confirm behaviour alongside Laravel's view caching — Phug has its own compile cache and the two must not fight or double-cache.
• Check interaction with opcache and read-only production filesystems: the compile cache must be writable and ideally outside the release directory.
• Validate against any existing View Composers, @vite/@livewire inclusion strategies, and localization in email templates.

Sequencing

Exit criteria for Phase 3 → 4 should be written down before Phase 1: no upstream commits in 6 months, a security advisory without a patch, or more than one production incident attributable to the engine all trigger removal.

Operational Impact

Maintenance

The recurring cost is not the package — it is the adapter, the cache lifecycle, and the version-pinning discipline. Expect an ongoing ~2–4 hours/month of platform-team attention, mostly upgrade testing and cache debugging. We own the Laravel glue indefinitely; upstream will not maintain it for us. Pin exactly, never use floating constraints, and treat upstream tags as code review events.

Support

Community-only, no SLA, small maintainer pool. Internally this must be owned by a named platform engineer with a documented fallback: extract Pug templates to plain PHP/HTML, delete the adapter, remove the dependency. That fallback should be rehearsed once in staging; if it takes more than a day, the dependency is too entrenched.

Scaling

Template compilation is CPU-bound and one-time per template version, so the steady-state cost is near zero — but only if the compile cache is warm and shared. Cold-cache behaviour on autoscaling or blue-green deploys is the scaling hazard: every new container recompiles every template on first hit. Mitigate by precompiling at build time (php artisan pug:compile in CI, artifact baked into the image) rather than lazily at runtime. If precompilation is not achievable, write the cache to a shared Redis/EFS volume and accept the network hop.

Failure modes

• Parse error at render time — a template typo becomes a runtime exception in a request path. Mitigate with a CI job that compiles all .pug files on every commit; this converts a runtime failure into a build failure and is the single highest-value control.
• Cache stampede on deploy — all containers recompile simultaneously. Mitigate with build-time precompilation.
• Stale cache after template edit — devs edit, see old output, lose an hour. Mitigate with a clear-cache command wired into local tooling and a mtime key in the cache hash.
• Silent output drift after upgrade — mitigate with HTML snapshot tests on every piloted template.
• Expression-evaluation exposure — if templates are ever surfaced to a non-engineer editing surface, this becomes RCE. Enforce that .pug files live only in the repo and pass code review.
• Upstream abandonment — mitigate with the rehearsed exit plan.

Ramp-up

Blade-fluent developers will need roughly half a day to become productive in Pug (indentation significance, mixins, interpolation, PHP expression syntax) and about a week to become idiomatic. Designers familiar with Jade/Pug onboard faster than engineers. Budget for a short internal guide covering our adapter's config, the cache-clear command, the CI lint step, and the "which engine do I use for this view" decision rule. Without that decision rule, teams will drift and you will end up with a two-engine codebase with no coherent boundary.

Recommendation: proceed to Phase 0–1 as a time-boxed spike only. The scores — 4 stars, 0 dependents, opportunity 23.12 — describe a niche component with no ecosystem reinforcement, and the gain over Blade is developer ergonomics rather than capability. Justify it with a concrete Pug corpus or designer-workflow requirement, or decline.