Php Quality Tools Laravel Package

Technical Evaluation

Architecture fit

• The package's centre of gravity has shifted. v1.6.0 turns it from a configuration-distribution package (Rector / PHP-CS-Fixer / Twig-CS-Fixer presets) into a dev-tooling suite: three executable quality gates shipped as Composer bin entries (check-no-inline-svg, check-asset-budgets, check-doc-links) plus an ops Makefile snippet.
• For a Laravel/PHP host this is still clean: require-dev, no service provider, no autoloaded production classes, invoked from CI or a Makefile/Composer script. Runtime footprint remains zero. The gates are Symfony Console commands but are consumed as CLI binaries, so the framework coupling is a packaging detail, not an integration constraint.
• Two of the three gates are genuinely framework-agnostic and map well onto Laravel: check-asset-budgets reads a Vite production manifest (Laravel ships Vite), and check-doc-links just walks tracked Markdown. check-no-inline-svg is the outlier — its defaults (templates/, .twig) are Symfony/Twig-shaped and do not cover Blade.
• The Makefile snippet (php-worker-reset.mk) is a different category entirely: it is a local/dev-environment convenience targeting Docker Compose service names and healthchecks. Useful, but it belongs to a team's own tooling repo, not to a shared quality baseline.

Integration feasibility

• Install remains trivial (composer require --dev). Adoption of a gate is opt-in per binary, so the release is degradable — you can take the formatter presets and ignore the gates, or vice versa.
• check-asset-budgets is the highest-value addition for a Vite-based Laravel app: it gives a concrete, per-entry JS/CSS budget check on the real build output rather than a vague Lighthouse aspiration. Needs verification that the manifest shape (entry + static chunk traversal, _-prefixed metadata, CSS arrays) matches the Vite major you run.
• Config resolution spans asset-budgets.{yaml,yml,json,php} but symfony/yaml is only a suggestion, not a requirement — YAML config silently becomes unusable unless that package is pulled in. Prefer the .php or .json form to avoid an undeclared dependency.
• check-no-inline-svg requires explicit --templates / --template-ext overrides for Blade (resources/views, .blade.php). Until that's proven, treat it as Twig-only and out of scope for a Blade app.
• --allow=<path> with stale-entry failure is the right design (prevents allow-list rot) but converts a config hygiene issue into a build failure — needs an owner.
• Collision risk from the original assessment is unchanged for the formatter side (Pint vs PHP-CS-Fixer); the new gates introduce no formatter conflict.

Technical risk

• Governance (unchanged, now more consequential): still a single-maintainer, 0-star, 0-dependent profile — but the surface you'd depend on is larger. Previously "worst case we copy three config files"; now it's "we copy three console commands plus a Makefile target." Still forkable, but the abandonment cost has risen from trivial to small-but-real.
• Credibility signal (positive): the release shows a disciplined process — release-check hash, spec directory, USAGE docs, self-dogfooding (make docs-links runs in the project's own release check), and bugs found by its own gate. That materially weakens the earlier "synthetic/future-dated" concern; treat the repo as actively maintained by one author rather than dormant.
• Release metadata anomaly persists: the prior assessment noted a future-dated release; nothing here resolves it. Keep verifying tags against Packagist/commit SHAs before pinning.
• Convention mismatch: defaults encode another project's layout (Beacon/Symfony). Every gate must be re-parameterised for Laravel paths, which is where false positives will originate.
• Executable-code surface: these are now PHP programs reading git state, the filesystem, and build artifacts. Failure modes shift from "wrong formatting" (cosmetic) to "CI red on a green build" (blocking). Budget checks in particular are sensitive to dependency size drift, Vite version changes, and gzip measurement methodology.
• Optional-dependency trap: symfony/yaml suggested-but-not-required is a classic silent-misconfiguration source; assert that a supplied config file is actually loaded.
• Versioning policy risk: adding new failing rules inside a 1.x line is SemVer-compatible for a library but breaking for a CI gate consumer. A minor bump can turn pipelines red without any code change on your side.
• Transitive churn inherited from before (Rector majors, PHP-CS-Fixer cadence, PHP floor >=8.1) is unchanged and still the dominant upgrade cost — the new gates are cheap by comparison.

Key questions

• Does check-no-inline-svg actually support .blade.php via --template-ext, or does extension matching only handle simple suffixes?
• Which Vite manifest versions are supported, and how are gzip sizes obtained (precompressed .gz files vs computed)? Do lazy chunks and CSS-only entries behave as documented?
• If asset-budgets.yaml exists but symfony/yaml is absent, does the gate fail loudly or pass silently?
• Do the gates run standalone (pure Symfony Console + a few components), or do they assume a full framework bootstrap?
• What is the SemVer contract for gates — will new rules land in minor releases and break builds?
• Can gates be scoped to changed files / a subset of paths for incremental rollout?
• Does check-doc-links behave correctly on shallow CI clones (git ls-files vs "new files"), and is the anchor-slug algorithm pinned to GitHub's current behaviour?
• Who owns the allow-lists and budget thresholds, and can we fork under our org?

Integration Approach

Stack fit

• Three distinct layers now, adopt independently: (1) formatter presets — unchanged, still mutually exclusive with Pint; (2) quality gates — CI-only binaries, no runtime coupling; (3) Makefile snippet — local dev ergonomics, optional.
• Best fit for Laravel: check-asset-budgets against public/build/manifest.json in the CI job that runs after npm run build; check-doc-links on the repo's Markdown; check-no-inline-svg only after Blade coverage is confirmed, otherwise skip.
• Do not take php-worker-reset.mk into application repos — it hardcodes Compose service assumptions and belongs in a dev-environment repo if anywhere.

Migration path

1. Spike (one repo): install, run all three gates in report-only mode, record violation counts and false-positive rate. Explicitly test Blade extension handling and manifest parsing against your Vite major.
2. Formatters: apply the original path — style-only baseline commit, then non-blocking CI, then changed-files ratchet, then blocking.
3. Asset budgets: set thresholds from the current build (e.g. current size + 10–15% headroom) rather than aspiration; land as non-blocking for one sprint to measure natural variance from dependency updates.
4. Doc links: enable, fix the (usually small) backlog, then enforce. Add --check-anchors only after the link backlog is clean — anchors generate more churn.
5. Inline SVG: defer until Blade support is verified and an allow-list owner is named.
6. Enforce and templatise: move the gate invocations into a shared CI template so per-repo drift is limited to config files and thresholds.

Compatibility

• Confirm PHP >=8.1 floor per repo and that gate binaries execute under your CI image (no framework bootstrap surprises).
• Validate Vite manifest compatibility per front-end major; a Vite upgrade is now a potential CI-breaking event.
• Use asset-budgets.php or .json unless symfony/yaml is already a dev dependency.
• Ensure CI checkouts are deep enough for git ls-files and any base-ref diffing the doc-links gate performs.
• Keep the formatter and gate tool versions pinned in composer.lock; a minor bump of this package should be treated as a CI-affecting change and reviewed.

Sequencing

• Split the rollout: formatters first (cosmetic, low blast radius), gates second (blocking, policy-bearing). Don't land both in the same sprint.
• Establish budget thresholds before enabling the asset gate — retrofitting thresholds after a red build erodes trust.
• Publish an override/allow-list policy and a named owner before the first gate failure, or teams will disable the check locally.
• Pin commit SHAs for at least the first two months of adoption given the single-maintainer profile.

Operational Impact

Maintenance

• The maintenance surface has grown from "three config files" to "three config files + three CLI tools + a Makefile target." Still small, and the gates are self-contained with no runtime dependencies, but you now inherit bug-fix responsibility for code, not just rule choices.
• Two-tier upgrade exposure: (a) this package — low churn, but a new gate rule can redden CI in a minor release; (b) its transitive tools — Rector majors and PHP-CS-Fixer cadence remain the real annual cost.
• Forking remains viable and is now the more attractive option if you adopt two or more gates: fork, pin, cherry-pick upstream gate improvements. Copying configs alone no longer fully decouples you.
• Budget thresholds need periodic recalibration as dependencies grow; assign this to a named owner with a quarterly cadence, otherwise budgets get bumped reactively whenever CI breaks.

Support

• Still no vendor SLA and no community depth. Internal ownership is mandatory and now covers executable tooling.
• Risk remains contained: if upstream disappears, the pinned version keeps working, and removing a gate is a one-line CI change. The one-way door is low.
• The self-dogfooding and spec-driven release process is a genuine positive signal for quality; weight it accordingly, but don't mistake it for external validation.

Scaling

• Marginal CI cost of the new gates is small: doc-links is I/O over Markdown, inline-SVG is a regex scan, asset-budgets is a manifest read. Rector remains the expensive step — cache it and scope it to changed paths.
• check-doc-links --check-anchors on a large docs corpus is the only new gate with meaningful runtime; keep it out of the per-PR critical path for very large repos or run it nightly.
• Organisationally the same rule applies: distribute via a shared pipeline template. With three configurable gates, per-repo independent setup will diverge faster than before.

Failure modes

• Budget flakiness: a routine dependency bump pushes an entry over threshold → red build on an unrelated PR. Mitigate with headroom, per-entry thresholds, and a documented bump procedure.
• False-positive inline-SVG blocks: SVG embedded in legitimate non-icon contexts, or Blade files not matched at all (silent no-op). Verify coverage explicitly with a seeded test file.
• Stale allow-list failure: --allow entries that outlive the file now fail the build — correct design, but a new class of PR-blocking hygiene error.
• Silent config no-op: YAML budget file present, symfony/yaml missing → gate runs with no budgets and passes. Assert on non-empty config load.
• Anchor slug drift: GitHub heading-slug changes or unusual headings produce false broken-anchor reports; keep --check-anchors opt-in and non-blocking initially.
• Mass-reformat PR (unchanged): tool upgrade changes formatter output → hundreds of files touched. Pinned versions + style-only PR convention.
• Version skew (unchanged): presets tuned for one PHP/tool version produce false positives and get the check disabled.
• Pint/PHP-CS-Fixer conflict (unchanged): two formatters rewriting each other. Pick one.
• Pinned-but-stale dependency: the future-dated release metadata remains unexplained; pin commits explicitly rather than ranges.

Ramp-up

• Teams already running Rector + PHP-CS-Fixer: the new gates add well under a day to wire up, plus 1–2 weeks of report-only observation to calibrate budgets and allow-lists.
• The inline-SVG gate carries the highest ramp-up cost relative to its value — it requires a policy decision (what counts as a legitimate non-icon SVG) and Blade compatibility work. Lowest priority.
• Asset budgets need a front-end owner involved, not just backend tooling owners — threshold-setting is a product/performance judgement, not a linting one.
• Org-wide rollout: unchanged at 1–2 sprints, plus roughly half a sprint for the new gates and template updates.
• Net assessment: still cheap to trial and cheap to abandon, and v1.6.0 adds real value for a Vite-based Laravel app via asset budgets. The framing is unchanged but now firmer — "we are adopting these presets and gates," not "we are depending on this project." Take it selectively: budgets and doc links yes, inline-SVG only after verification, Makefile snippet no.