Coding Standards Laravel Package

Getting Started

This is a PHP_CodeSniffer ruleset, not a framework integration package — it does nothing at Laravel runtime. You install it as a dev dependency and point phpcs/phpcbf at it.

composer require --dev arxeiss/coding-standards
composer require --dev squizlabs/php_codesniffer

The package ships a ruleset.xml exposing a named standard (check the README for the exact name — typically matches the package, e.g. Arxeiss). Verify it is discoverable:

vendor/bin/phpcs -i

If the standard is listed, auto-registration worked (via dealerdirect/phpcodesniffer-composer-installer). If not, you must reference the ruleset by path.

First use case: create a project phpcs.xml.dist at the repo root and run against a single file before touching CI:

<?xml version="1.0"?>
<ruleset name="App">
    <file>app</file>
    <file>routes</file>
    <file>tests</file>

    <rule ref="Arxeiss"/>
</ruleset>

vendor/bin/phpcs --standard=phpcs.xml.dist app/Http/Controllers/UserController.php

Look first at: the package's ruleset.xml (that is the documentation — every included/excluded sniff is spelled out there), then phpcs -e to see registered sniffs, then phpcs --report=source on your codebase to see what it will actually flag before you commit to it.

Implementation Patterns

Composer scripts as the single entry point. Every dev runs lint the same way, and CI calls the same script:

"scripts": {
    "lint": "phpcs --standard=phpcs.xml.dist",
    "lint:fix": "phpcbf --standard=phpcs.xml.dist",
    "lint:files": "phpcs --standard=phpcs.xml.dist --report=full"
}

CI with a diffable report. --report=checkstyle (or --report=github) gives per-line annotations in pull requests. Run phpcbf in a separate "autofix" job that opens a commit, not in the blocking job — otherwise developers get style failures they can't see locally.

Layered ruleset: package standard + project overrides. Treat the package as a base, then widen or narrow:

<rule ref="Arxeiss">
    <!-- package sniffs you disagree with, at project scope -->
    <exclude name="Arxeiss.Some.Category"/>
</rule>

<!-- project-specific additions -->
<rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint"/>
<rule ref="Generic.Files.LineLength">
    <properties>
        <property name="lineLimit" value="120"/>
    </properties>
</rule>

Property overrides on a sniff already in the package ruleset are the most common day-to-day adjustment — you rarely need a whole separate standard.

Incremental adoption on an existing Laravel app. Do not turn it on for the full tree on day one. Two practical strategies:

• Path scoping: <file>app</file> only, then add routes, tests, config over time.
• Severity gating: keep the standard at <arg name="severity" value="0"/> and set severity="0" on the loudest sniffs until the codebase is clean; the rule stays declarative and you flip severities as you pay down debt.

PhpStorm wiring. Settings → PHP → Quality Tools → Code Sniffer: set the PHPCS path to vendor/bin/phpcs and configuration to phpcs.xml.dist. Then enable the inspection. phpcbf maps cleanly to "Reformat code" once a sniffer has a fixer, so most style nits become Alt+Enter.

Pair with a static analyzer, don't expect this to substitute. PHPCS on this ruleset enforces style and some correctness patterns; it will not catch type errors. The useful split is: phpcs for style/lint in pre-commit (fast), PHPStan/Larastan for types in CI (slow). Running PHPCS alone and calling the codebase "checked" is the trap.

Pre-commit hook limited to changed files:

git diff --cached --name-only --diff-filter=ACM | grep '\.php$' \
  | xargs -r vendor/bin/phpcs --standard=phpcs.xml.dist

Note phpcs re-reads its full config per invocation, so this is noticeably slower than a full run on large file counts — use it as a fast gate, not as your only CI step.

Gotchas and Tips

Composer plugin allow-list. If dealerdirect/phpcodesniffer-composer-installer is blocked by allow-plugins, the standard silently never registers and phpcs -i won't list it. Either allow the plugin or reference the ruleset by path (--standard=vendor/arxeiss/coding-standards/ruleset.xml). This is by far the most common "it doesn't work" cause.

PHPCS 3.x vs 4.x. PHP_CodeSniffer 4 moved to the phpcsstandards/php_codesniffer fork and changed APIs; older sniffs break. Pin both sides in composer.json ("squizlabs/php_codesniffer": "^3.9" or the fork) and check this package's own constraint before upgrading PHPCS — a ruleset written against 3.x may reference sniff APIs that no longer exist.

Standard name resolution is case- and directory-sensitive. ref="arxeiss/coding-standards" won't work; you need the standard name (the name attribute inside the package's ruleset.xml), and it's usually not the Composer package name. When in doubt, run phpcs -i and copy the exact string.

exclude vs exclude-pattern. <exclude name="..."/> removes a sniff; <exclude-pattern> skips files. Confusing them means you write a sniffer exclusion and wonder why generated files still fail. Exclude storage/, bootstrap/cache/, public/build/, and _ide_helper*.php explicitly — the standard won't know your Laravel layout.

Sniff message codes are your debugging lever. A failure reads like PSR12.Files.FileHeader.SpacingAfterBlock — the middle segments identify the standard, sniff, and specific message. Use that exact path in <exclude name="..."/>; a bare sniff name silently does nothing and gives no warning. Verify exclusions by re-running the file and confirming the message count dropped.

Severity vs. disable — prefer severity for legacy. Setting a sniff to severity="0" keeps it in the ruleset (so it's visible in review) while not failing the build. Deleting it means everyone forgets it existed. This matters if you're onboarding an existing app; the diff between "we disabled it" and "we never had it" is lost during the next config cleanup.

Don't fight the package's opinions on formatting-only diffs. The value of a shared ruleset is uniformity, not that any particular rule is correct. If a sniff disagrees with your whole team, exclude it once at project level and move on — per-file phpcs:ignore annotations scattered through app/ are the anti-pattern that kills adoption.

Extension points are limited to what ruleset.xml exposes. You can exclude sniffs, override properties, and merge other standards — but you cannot subclass a sniff here. If you need custom behavior (Laravel-specific rules, e.g. no facades in a domain layer), write your own sniff under a separate standard and <rule ref="MyStandard"/> alongside this one. The package is a base to compose, not a framework to extend.

Generated and migrated files drift. Laravel migrations created by make:migration and model stubs are usually format-dirty out of the box. Either exclude database/migrations from the ruleset or run phpcbf on them once after generation — otherwise every new migration adds a spurious failure and trains people to ignore lint output.