Layouts Coding Standard Laravel Package

Getting Started

This package is a PHP_CodeSniffer ruleset — not a runtime library. There is no service provider to register, no facade to call. A Laravel developer's entire interaction with it is composer require --dev, a phpcs.xml.dist, and the phpcs/phpcbf binaries. If you are not working on a Netgen Layouts (Symfony) codebase, stop here — the correct Laravel equivalent is Laravel Pint or PSR-12 + Slevomat.

Minimal setup:

composer require --dev netgen/layouts-coding-standard

Create phpcs.xml.dist at the project root:

<?xml version="1.0"?>
<ruleset name="Project">
    <description>Netgen Layouts coding standard</description>

    <file>src</file>
    <file>tests</file>

    <arg name="extensions" value="php"/>
    <arg name="colors"/>
    <arg name="parallel" value="8"/>

    <!-- Include the bundled ruleset; check the exact path/name -->
    <rule ref="vendor/netgen/layouts-coding-standard/ruleset.xml"/>
</ruleset>

Where to look first:

1. vendor/netgen/layouts-coding-standard/ruleset.xml — this is the single source of truth. It tells you the standard's registered name (if any) and, crucially, which other standards it <rule ref="...">s (slevomat/coding-standard, doctrine/coding-standard, PSR-12, etc.). If those aren't installed transitively, PHPCS will throw "Referenced sniff ... does not exist" at load time.
2. The package's composer.json — confirm which PHPCS major (squizlabs/php_codesniffer ^3 vs phpcsstandards/php_codesniffer ^4) it targets and its PHP floor. Mismatches are the #1 install failure.
3. The README.md — usually has the canonical vendor/bin/phpcs --standard=... invocation to lift into CI.

First use case: run in report-only mode against the Layouts-specific directories of your codebase (custom blocks, layout definitions, extensions), not the whole app:

vendor/bin/phpcs -s --standard=phpcs.xml.dist src/Layouts

Capture the violation surface, then decide whether it is a small cleanup or a baseline job.

Implementation Patterns

Composer scripts are the entry point. Never make teammates memorize paths:

"scripts": {
    "cs": "phpcs",
    "cs:fix": "phpcbf"
}

Because phpcs auto-discovers phpcs.xml.dist, composer cs just works and the ruleset stays centralized.

Layer your overrides, never edit inside vendor/. Extend the vendor ruleset and add project-specific exclusions on top:

<rule ref="vendor/netgen/layouts-coding-standard/ruleset.xml">
    <exclude name="SlevomatCodingStandard.Files.TypeNameMatchesFileName"/>
</rule>

<rule ref="Generic.Files.LineLength">
    <properties>
        <property name="lineLimit" value="120"/>
    </properties>
</rule>

This survives composer update and documents your divergences in one place.

Baseline before you block the build. Generate a baseline so legacy violations don't freeze feature work:

vendor/bin/phpcs --standard=phpcs.xml.dist --generated-baseline

Commit phpcs.baseline.xml and reference it from phpcs.xml.dist. New violations will fail; old ones are grandfathered. Clean the baseline down incrementally.

Gate only changed code in CI while the baseline is still large. On GitHub Actions:

- run: composer install --no-interaction --prefer-dist
- run: vendor/bin/phpcs --standard=phpcs.xml.dist --report=checkstyle --report-file=phpcs.xml

If your pipeline already uses reviewdog or phpcs-changed, wire it to the same phpcs.xml.dist so only diff lines are linted. This is what keeps the PR review signal meaningful during remediation.

Pre-commit hook (optional but high-leverage). captainhook or a raw pre-commit calling composer cs:fix on staged files, then git add, catches 80% of style churn before it reaches CI — and developers only see errors on their own diffs.

Coexistence with Pint / PHP-CS-Fixer. Do not run both tools that claim ownership of style. If your Laravel-adjacent tooling uses Pint, either (a) point Pint's config at the same conventions as this ruleset, or (b) make PHPCS this package's ruleset the sole gate and drop Pint. Two style owners produce a fight that ends with one being silently removed from CI.

PHPCBF in a dedicated commit. Any first composer cs:fix against a real codebase will touch dozens of files with no behavioral change. Land it as an isolated "style only" commit — reviewers can then trust that subsequent functional diffs contain only logic.

Gotchas and Tips

This is not Laravel tooling. The name says "coding-standard," but the rules encode Netgen Layouts (Symfony bundle) conventions. There is no facades, no Eloquent, no Blade-specific sniff. Applying it to a Laravel app produces noise that teams will eventually mute — strictly worse than never installing it. Only adopt if Netgen Layouts is genuinely in the stack.

Wrong ruleset name is the #1 rookie error. You cannot write <rule ref="NetgenLayouts"/> unless the package registers that as a standard name. Read ruleset.xml and copy the include path verbatim — usually vendor/netgen/layouts-coding-standard/ruleset.xml.

PHPCS major version trap. If the ruleset declares squizlabs/php_codesniffer ^3 and your project resolved ^4 (which is now phpcsstandards/php_codesniffer), sniffs may not resolve or behaviour changes silently. Pin both consistently in composer.json.

Missing transitive standards. If slevomat/coding-standard or doctrine/coding-standard are not pulled in as hard dependencies of this package, phpcs will fail on load with "Referenced sniff ... does not exist." Add them explicitly:

composer require --dev slevomat/coding-standard

No community backstop. Zero stars, zero dependents, single-vendor origin. Treat upstream as best-effort: pin an exact version, and be prepared to fork into a private repo. The MIT license makes the fork cheap; the discipline is what saves you when a PHPCS 4 bump breaks the sniffs and no upstream PR appears.

Slow lint kills enforcement. If the CI lint job exceeds a few minutes, teams quietly stop fixing violations. Always set <arg name="parallel" value="8"/> (or higher), scope <file> to relevant paths in a monorepo, and enable caching at the runner level. Performance of the lint step is the real adoption risk, not style philosophy.

Conflicting sniffs on the same token. When this ruleset overlaps with an existing standard (PSR-12 base, Slevomat, or a Laravel-inherited config), some sniffs fire contradictory fixes. Resolve by explicit <exclude name="..."/> in your project ruleset — never by file ordering, which is fragile and undocumented.

Autofix is not always safe. phpcbf will happily reorder imports, collapse arrays, and reformat long lines in a way that can alter merge-conflict surface on long-lived branches. Run it on a fresh branch, keep the diff to style-only, and merge before any significant functional work is in flight.

Version bumps are their own PR. Never float the package as ^1.0 in a project that is actively being reviewed. Bump versions in a dedicated commit, run the full lint locally, and confirm CI stays green before merging. A silent Tuesday ruleset change that turns the build red erodes trust in the gate faster than no gate at all.