Formatter Laravel Package

Technical Evaluation

Architecture fit

• phug/formatter is a pure-PHP library, not a service. It consumes the Phug AST (hence the repo link to phug-php/ast) and re-serializes Pug source. It has no framework coupling — it will drop into any Composer-managed PHP 8.x codebase, Laravel included.
• Fit is binary: if the product renders Pug templates through phug/renderer or tale-pug, this is a natural dev-tooling dependency. If the stack is Blade-only, there is no fit and no reason to read further.
• It is a developer-tooling artifact, not a runtime dependency. The correct architectural placement is require-dev, invoked from CLI/CI — not from request-cycle code.

Integration feasibility

• High. composer require --dev phug/formatter, instantiate the formatter, pass source strings, get formatted Pug back. Expect a thin artisan pug:format wrapper to be a day of work.
• The cost is not wiring, it is output trust: verifying that formatting does not alter rendered HTML. Pug is whitespace-sensitive, so semantic drift is the dominant integration cost, not API plumbing.

Technical risk

• Repository metadata mismatch: the package is phug/formatter but the listed repository is phug-php/ast. For a supply-chain or license audit, this is a provenance gap that must be resolved before adoption. MIT is confirmed, which mitigates the licensing dimension.
• 2 stars / 0 dependents is a negative signal on validation, not necessarily on quality. There is no public evidence of anyone running this in production, so you are the first meaningful test case.
• Bus factor is effectively one. The Phug ecosystem is a single-maintainer project; a breaking parser change upstream can strand this package.
• Opportunity score of 25.89 is low; combined with the near-zero dependent count, treat this as a build-or-fork candidate rather than a strategic dependency.

Key questions

1. Which phug/ast and phug/parser versions does the formatter constrain, and are those constraints tight enough to prevent silent AST-node drift?
2. Is the formatting operation idempotent? (Run twice, diff twice — must be empty.)
3. Does it preserve whitespace-significant constructs (|, pre, textarea, inline tags) without changing rendered output?
4. How does it behave on include/extends/block/mixin — single-file only, or does it traverse?
5. What is the failure mode on malformed input — exception, partial output, or silent corruption?
6. Why does the repository field point at ast rather than formatter? Is the formatter actually part of that monorepo, and is the released package built from it?

Integration Approach

Stack fit

• Laravel 10/11/12 on PHP 8.1+ is the assumed target. The package pulls phug/ast and a parser transitively, so your effective surface is three packages, not one.
• Pin all three explicitly in composer.json. Do not rely on transitive resolution — with zero dependents there is no ecosystem pressure keeping these versions coherent.

Migration path

1. Inventory existing .pug files and classify by feature usage (mixin-heavy, include-heavy, plain markup). Format only a representative subset first.
2. Batch apply on a dedicated branch, one commit per directory, so any semantic regression is bisectable.
3. Render-diff harness: compile each template before and after formatting and compare rendered HTML byte-for-byte. This is the only acceptance gate that matters.
4. CI enforcement as --check (fail on unformatted) only after the render-diff suite is green and stable across two weeks.

Compatibility

• The hard constraint is parser version parity between what the formatter expects and what your renderer resolves. If production rendering and formatting use different parser versions, formatting can produce syntax the renderer rejects — or vice versa.
• Editor integration is the weak link: no evidence of a maintained PhpStorm/VS Code plugin. Plan for CLI-only and an npm/make shortcut rather than expecting format-on-save.

Sequencing

• Week 1: provenance audit + render-diff harness.
• Week 2: format a non-critical module, monitor CI.
• Week 3+: expand coverage module-by-module; add pre-commit hook last, never first.

Operational Impact

Maintenance

• You inherit the maintenance risk. With one maintainer and no dependents, assume you will fork within 18 months. MIT makes that cheap; budget the time anyway.
• A 2026-03-15 release date suggests the package is still being cut, which is mildly reassuring on liveness but says nothing about stability — verify whether releases are feature or fix driven.

Support

• GitHub issues only. No vendor, no SLA, no paid tier. Internal escalation path must terminate at your own engineers.
• Document the formatter's known-unsupported syntax in your repo, not upstream — you will be the authority on it.

Scaling

• Trivially scalable: CPU-bound, stateless, file-at-a-time. Parallelize across files in CI. There is no runtime scaling dimension because this never serves traffic.
• The real scaling cost is CI minutes and review noise: a formatter that is not idempotent produces churn every run, which compounds across a large template corpus.

Failure modes

• Semantic drift — formatting alters whitespace in a way that changes rendered HTML. Highest severity, hardest to detect without the render-diff harness. Mitigate: gate on it, non-negotiable.
• Parser crash on exotic-but-valid Pug — formatting aborts mid-corpus. Mitigate: per-file isolation, continue-on-error, quarantine list.
• Version-skew breakage — upstream phug/ast refactor breaks node handling after a composer update. Mitigate: pin exact versions, renovate with manual approval.
• Non-idempotent output — CI fails on already-formatted files. Detect in week 1 with the double-run diff.

Ramp-up

• Low for anyone who already writes Pug; the tool is invisible once wired into CI. One page of internal docs covering the artisan command, the quarantine list, and the escalation path to the fork is sufficient.
• The genuine ramp-up cost sits with the one or two engineers who own the fork contingency — they need to read the AST package, which is the real learning curve here.

Bottom line: adopt as a require-dev convenience with a pinned fork-ready posture and a mandatory render-diff gate. Do not treat it as infrastructure, and resolve the repository-provenance mismatch before it enters the dependency graph.