Php Quality Tools Laravel Package

Product Decisions This Supports

• Standardizing the PHP quality baseline across repositories. The package bundles pre-configured Rector, PHP-CS-Fixer, and Twig-CS-Fixer, so the PM decision it informs is "do we adopt a shared, opinionated quality config instead of each team hand-rolling one?" That is a recurring, low-drama decision that directly affects review velocity and merge friction.
• Build vs. buy for internal quality tooling. As of v1.6.0 the scope has widened: it is no longer only a config bundle but also ships executable gates (bin/check-no-inline-svg, bin/check-asset-budgets, bin/check-doc-links) ported from Symfony Beacon's internal scripts. The build-vs-buy question is now "maintain our own shared configs and our own CI gate scripts vs. consume this one." Switching cost is still low (dev-only, thin, MIT), but the surface you'd have to replace or vendor has grown from config files to config files plus three commands.
• CI/CD roadmap and gate design. Adoption is a prerequisite decision for adding automated style/refactor checks to pipelines, and now also for front-end and documentation gates: "do we fail builds on inline SVG?", "do we enforce per-entry JS/CSS byte budgets?", "do we fail on broken relative links in Markdown?" Each of those is a real policy decision with workflow and build-time consequences, and this release moves them from "someday" to "one dependency away."
• Performance budgets as a product requirement. check-asset-budgets reads Vite production manifests and enforces raw + gzip size budgets per entry (entry and statically imported chunks only; lazy chunks excluded). That supports a decision to treat bundle size as an enforceable, reviewable product constraint rather than a periodic manual audit — with the important nuance that lazy-loaded chunks are not counted, so it governs first-load weight, not total payload.
• Design-system and icon governance. check-no-inline-svg turns "icons come from the icon set, not pasted markup" into a build failure across templates and front-end scripts, with an explicit --allow list whose stale entries also fail. That supports decisions about how strictly a design system is enforced versus documented.
• Documentation quality as a maintained surface. check-doc-links covers broken relative links and images in tracked Markdown, with opt-in --check-anchors for heading slugs, HTML anchors, and {#id} attributes. This supports the decision to treat docs as a gated artifact (useful for public docs, onboarding guides, ADR folders) rather than a best-effort one.
• Developer experience for asset builds. resources/make/php-worker-reset.mk addresses stale Vite entrypoints in long-lived PHP workers by clearing cache, restarting the PHP service (and an optional second stack), and waiting for healthy. This supports a decision to codify the "rebuild → reset workers" ritual into the Makefile instead of tribal knowledge.
• Supply-chain and dependency policy review. Still a single-maintainer package with negligible adoption, now with a larger footprint (three new bin entries) — but no new require entries; symfony/yaml remains a suggestion covering the asset-budget config. The policy question becomes: is this acceptable as a dev-only dependency as its scope grows, and under what pinning/mirroring rules?

When to Consider This Package

Consider it when:

• The project is a PHP 8.1+ / Symfony 6/7/8 codebase, especially one using Twig.
• You have a Vite front end and care about first-load weight — check-asset-budgets is the strongest new reason to adopt, because size budgets are otherwise fiddly to wire into a PHP-centric pipeline.
• You ship Markdown documentation that outsiders or new hires read, and broken links are a recurring annoyance worth gating.
• You have an icon/design-system convention that keeps slipping into copy-pasted <svg> markup.
• You want a fast, low-effort quality baseline and are willing to accept someone else's opinionated defaults as a starting point.
• The dependency can be scoped as dev-only (require-dev), keeping runtime risk near zero and making removal a one-line change.
• Your team is small or lacks someone who wants to own a shared config and CI gate package, so maintenance leverage outweighs bespoke control.
• You need Rector + PHP-CS-Fixer + Twig-CS-Fixer + front-end/docs gates from one install rather than assembling and version-pinning several separate tools.
• You can pin an exact version and review the configs and commands before rollout — reasonable for a package whose value is literally its configuration and its gate logic.

Look elsewhere or defer when:

• Adoption signals matter to your process. Still zero stars, zero dependents, no community validation, no third-party bug reports. Growing scope without growing adoption is a mild negative signal, not a positive one.
• You need responsive upstream support. Single maintainer, no proven support load; the three new gates are ports of another project's internal scripts, so bug reports will be sparse. Assume you may fork or vendor.
• Your stack is headless or non-Symfony. With v1.6.0 the package is more useful to a Symfony + Vite + Twig + Markdown monorepo and no more useful to a plain PHP API — for the latter, the Twig, Vite, and docs gates are all dead weight and the value collapses to "a PHP-CS-Fixer preset."
• You already use mature JS-side equivalents. size-limit/bundlesize for budgets, lychee/markdown-link-check for links, an ESLint rule for inline SVG. The new gates' advantage is consolidation into one PHP toolchain, not unique capability — if your front-end already has that tooling, adding a second enforcement path creates duplicate sources of truth.
• You need heavily configurable gates. These are opinionated ports with flag-level customization (--allow, --budget, --exclude, extensions, --root); anything more bespoke means maintaining a fork.
• You already have an established toolchain. Migration cost likely exceeds benefit — this is a starting point, not a migration target.
• Strict supply-chain controls apply (regulated environments, reproducible builds). Verify release provenance and consider vendoring configs and commands directly; note the release does carry a release-check hash, which is a mild positive for provenance review.
• You are evaluating release health. Cadence still looks thin, and the new commands are day-one code with no field usage outside the origin project. Run each gate in report-only mode before making it blocking, and confirm it behaves on your repo's directory layout (the defaults assume templates/, assets/, and a git working tree).

How to Pitch It (Stakeholders)

For executives (one paragraph): We can standardize code quality across our PHP/Symfony projects with a small, MIT-licensed, development-only package. It pre-configures three widely used tools — Rector, PHP-CS-Fixer, and Twig-CS-Fixer — and, as of this release, adds three CI gates: front-end bundle-size budgets from our Vite build, broken-link checks for our Markdown docs, and a ban on inline SVG outside our icon set. Cost is near zero and risk is bounded: it ships no runtime code, adds no new production dependencies, and can be removed in a single dependency change. The benefit is fewer style debates in review, faster onboarding, docs that don't rot, and a size budget that fails the build instead of surprising us in production. The caveat to disclose up front: the package still has no visible community adoption, and the three new gates are recent ports from another project's internal scripts — so we should treat it as a toolbox we control, pin the version, review the shipped configs and gate logic, and be prepared to vendor them if upstream stalls. Recommend a time-boxed pilot on one or two repositories, starting with the size-budget gate in report-only mode.

For engineering leads: Still a config-plus-gates bundle, not a framework. It gives us Rector, PHP-CS-Fixer, and Twig-CS-Fixer with opinionated defaults, plus three commands we can wire into CI: check-asset-budgets (per-entry raw and gzip JS/CSS budgets from the Vite manifest), check-doc-links (relative links/images, optional --check-anchors), and check-no-inline-svg (templates and front-end scripts, with a stale-allow-list check). Install as require-dev, pin the version, diff the shipped configs against our current setup, and run each gate in report-only mode for a sprint before making it blocking. Things to verify before adoption: (1) defaults match our PHP 8.1+/Symfony 6–8 target; (2) Rector rule sets don't silently apply risky refactors — dry-run first; (3) budget semantics fit us — lazy chunks are excluded, so this checks first-load weight, not total payload, and gzip assumes we serve compressed assets; (4) the docs gate sees the right files (it uses git ls-files inside a repo, a tree walk outside) and that --check-anchors slug matching agrees with our Markdown renderer; (5) symfony/yaml is only a suggestion — if we configure budgets via YAML rather than JSON/PHP or --budget flags, we must add it ourselves. Because the package is thin, forking or copying the configs and commands into our repo remains a cheap fallback.

For the pilot team: Treat this as an experiment with a clear exit criterion per gate, and don't adopt all four at once. Suggested sequencing: start with check-asset-budgets in report-only mode and calibrate thresholds against the current build, then check-doc-links without --check-anchors (lowest false-positive risk), then anchors, then the inline-SVG gate last since it touches both templates and scripts. Success = gates run on every PR, false-positive churn stays under an agreed threshold over two weeks, and new contributors pass without manual config work. Failure = frequent overrides or allow-list entries, or conflicts with our existing standards. Either outcome is informative and cheap.