Coding Standard Laravel Package

Getting Started

composer require --dev vierwd/coding-standard squizlabs/php_codesniffer

The package is a PHP_CodeSniffer ruleset, not a standalone linter, so PHPCS must be present. Registration is the step people trip on: PHPCS only sees a standard if its path is in installed_paths. Either install the auto-registrar:

composer require --dev dealerdirect/phpcodesniffer-composer-installer

(and allow it with "config": { "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true } }), or register manually:

vendor/bin/phpcs --config-set installed_paths vendor/vierwd/coding-standard

Verify before doing anything else:

vendor/bin/phpcs -i        # "Vierwd" must appear in the list

Then drop a phpcs.xml.dist in the project root so plain vendor/bin/phpcs works with no arguments:

<?xml version="1.0"?>
<ruleset name="App">
    <description>App coding standard</description>
    <file>app</file>
    <file>config</file>
    <file>database</file>
    <file>routes</file>
    <file>tests</file>
    <arg name="extensions" value="php"/>
    <arg name="colors"/>
    <arg value="sp"/>
    <rule ref="Vierwd"/>
</ruleset>

Look first at the package's Vierwd/ruleset.xml — there is no meaningful documentation, and 0 stars means no blog posts to lean on. The XML is the spec: it tells you which upstream sniffs (PSR-12, Slevomat, etc.) are included, excluded, and configured. Read it before you argue with a violation.

First real use case: run vendor/bin/phpcs --report=summary on an existing Laravel app. You will get thousands of violations. The summary report groups by sniff, which tells you which two or three sniffs dominate — usually whitespace/alignment and unused imports. Fix those with phpcbf first; the long tail of semantic violations is where the actual review work is.

Implementation Patterns

Composer scripts as the entry point. Never expect a teammate to remember flags:

"scripts": {
    "lint": "phpcs",
    "lint:fix": "phpcbf",
    "check": ["@lint", "@php artisan test"]
}

CI via cs2pr. Checkstyle output plus cs2pr turns violations into inline PR annotations, which is the difference between "the linter failed" and "fix line 42":

vendor/bin/phpcs --report=checkstyle | cs2pr

Baseline for legacy codebases. PHPCS 3.6+ supports baselines, and this is the only sane way to adopt a strict external standard on a mature Laravel app:

vendor/bin/phpcs --baseline=phpcs-baseline.xml
git add phpcs-baseline.xml

Commit it, and from then on only new violations fail the build. Periodically delete entries as you clean up files — a baseline that only grows is technical debt with a CI badge.

Layering with Laravel Pint. Pint is PHP-CS-Fixer-based, so it cannot consume PHPCS sniffs, and the two will fight over alignment and spacing if you let them. Pick one authority: run Pint first for formatting, then PHPCS for the sniffs Pint cannot express (naming conventions, unused imports, strict comparisons, forbidden functions). Where the overlap causes ping-pong, exclude the PHPCS formatting sniffs in your ruleset rather than dropping Pint:

<rule ref="Vierwd">
    <exclude name="Vierwd.WhiteSpace.*"/>
</rule>

Scoped relaxations instead of global ones. tests/ and database/migrations/ rarely deserve the same strictness as app/:

<rule ref="Vierwd">
    <exclude name="Generic.Files.LineLength"/>
</rule>

wrapped in <rule ref="Vierwd"><exclude .../></rule> inside a path-scoped block (<rule ref="Vierwd"><exclude name="..."/></rule> under <file>tests</file> context) keeps production code strict while letting fixtures be ugly.

Editor integration. Point PhpStorm's Code Sniffer settings at vendor/bin/phpcs and the standard at your phpcs.xml.dist; for VS Code the phpcs extension reads the same file. Live feedback while typing is the whole value proposition of a coding standard — a CI-only lint is a tax you pay at the worst moment.

Pre-commit hook. Lint only staged files, because a full PHPCS run on a large repo is slow and PHPCS has no result cache (unlike Pint):

vendor/bin/phpcs $(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')

GrumPHP or a plain .git/hooks/pre-commit both work; the flag-based approach above is fine for most teams.

Gotchas and Tips

The package is stale. Last release was November 2022, and it pins against PHP_CodeSniffer 3.x. On PHP 8.3+ or if something pulls in PHPCS 4, expect deprecation noise and sniffs that misbehave. Pin explicitly: "squizlabs/php_codesniffer": "^3.7". Treat the standard as a frozen artifact, not something that will track new PHP syntax.

Zero stars, zero dependents, no docs. You are the maintainer now. Be ready to fork it into tools/phpcs/ or a private VCS repo the moment you need a rule change, because upstream PRs may never be reviewed. Vendor the ruleset rather than editing vendor/ — Composer will overwrite you on the next install.

phpcs -i not listing Vierwd is the #1 failure. It means installed_paths is wrong or the installer plugin wasn't allowed. Worse, --config-set writes to a per-machine config file that does not exist on a fresh CI checkout, so a locally-passing lint can fail mysteriously in CI. Prefer the installer plugin, or pass the path directly: --standard=vendor/vierwd/coding-standard/Vierwd.

phpcbf is not safe to run blind. It will not fix naming or line-length, and for some sniffs it rewrites code in ways you want to review — heredocs, multi-line alignment, closure formatting. Commit before running it, then diff the result. On a first run across a whole app, git diff is unreadable; do it directory by directory.

Laravel paths that must be excluded: bootstrap/cache, storage, public, vendor, and compiled views. If you omit <arg name="extensions" value="php"/>, PHPCS may try to sniff .blade.php files as PHP and produce nonsense. The config/ directory is usually safe but full of env() calls that some sniffs flag — exclude those sniffs rather than the directory.

Facades and helpers trip "global function" and naming sniffs. app(), config(), dd() may be flagged as discouraged globals depending on how the ruleset configures them. Add targeted excludes for the specific sniff plus the specific symbol; disabling a whole sniff to silence one false positive is how standards rot.

Baselines hide more than you think. Entries are keyed by file path and message hash, so renaming or moving a file invalidates them and re-surfaces old violations. After any big refactor, regenerate the baseline deliberately rather than letting it drift. Never baseline app/ — baseline the legacy corners only.

Line length and alignment sniffs conflict with Pint's defaults. If developers run both on save, they get a file that changes every time. Decide once, document it in the repo README, and enforce order in the pre-commit hook so the outcome is deterministic.

Extension point is your own ruleset, not config flags. Build phpcs.xml.dist that refs Vierwd and layers your additions on top. If you need per-project PHP version behavior, use --runtime-set php_version 80300 rather than editing the ruleset, so the same artifact works across projects with different PHP targets.

Pin to a commit, not a branch. There is no meaningful release cadence to rely on; "vierwd/coding-standard": "dev-master#<sha>" keeps CI reproducible when upstream eventually pushes something.