Laravel Phpcs Laravel Package

Getting Started

Install as a dev dependency alongside PHP_CodeSniffer itself (the package ships a ruleset, not the sniffer):

composer require --dev squizlabs/php_codesniffer mreduar/laravel-phpcs

The ruleset is registered with PHPCS through dealerdirect/phpcodesniffer-composer-installer. If that plugin is blocked in your project, add the path manually in composer.json:

"extra": {
  "phpcodesniffer-search-depth": 4
}

…or set installed_paths via vendor/bin/phpcs --config-set installed_paths vendor/mreduar/laravel-phpcs.

First place to look: run vendor/bin/phpcs -i — it prints every registered standard. The Laravel ruleset will appear there (typically as Laravel). That name is the value you reference in your project ruleset, and it's the fastest way to confirm the install actually worked before debugging anything else.

Minimal phpcs.xml at the project root:

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

First use case: run vendor/bin/phpcs on a single file or directory to see the delta between your code and Laravel style:

vendor/bin/phpcs app/Http/Controllers/UserController.php
vendor/bin/phpcbf app/Http/Controllers/UserController.php

Most teams adopt it as a pre-commit gate on app/ first, then widen to tests/ and database/ once the signal is clean.

Implementation Patterns

Composer scripts as the entry point. Don't make developers remember raw phpcs flags. Wire two scripts:

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

Now composer lint and composer lint:fix work regardless of where vendor binaries land on a teammate's machine.

CI gate (GitHub Actions). Keep it dumb — run the same command locally and in CI:

- run: composer install --no-interaction --prefer-dist
- run: composer lint

Because the ruleset lives in phpcs.xml (committed), CI and local runs cannot drift.

Editor integration. Point PHPStorm's Settings → PHP → Quality Tools → PHP_CodeSniffer at vendor/bin/phpcs, then configure Inspections → PHP CodeSniffer validation with the Laravel standard. For VS Code, ikappas.phpcs reads the same phpcs.xml automatically. This is where the package earns its keep — style nits get flagged as you type instead of in a PR review.

Layered rulesets per directory. If tests/ or legacy code shouldn't be held to the same bar, use <exclude-pattern> rather than separate configs:

<rule ref="Laravel">
    <exclude-pattern>database/migrations/*</exclude-pattern>
    <exclude-pattern>app/Legacy/*</exclude-pattern>
</rule>

Pre-commit hooks. Combine with captainhook or a plain .git/hooks/pre-commit calling vendor/bin/phpcs --filter=gitstaged (via phpcs-git-pre-commit or similar) so only staged files are checked — full-repo runs on commit are too slow for large apps.

Sniff-level overrides. When you disagree with one rule, don't abandon the standard — disable the specific sniff:

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

This keeps the rest of the ruleset intact while documenting the deviation in version control.

Pairing with Pint. Laravel's own laravel/pint overlaps heavily. If you're already on Pint, use this package purely as a read-only check (phpcs), not phpcbf, to avoid two formatters fighting over the same lines. See Gotchas.

Gotchas and Tips

Last release was November 2022. Laravel's own style has moved since — notably Pint ships with preset changes and newer PHP syntax rules. Treat this ruleset as a snapshot, not the authoritative source. If a rule feels wrong against current Laravel code, check laravel/pint's preset before assuming your code is at fault.

Standard name is not always obvious. If vendor/bin/phpcs -i doesn't list Laravel, the composer plugin didn't run or was blocked by allow-plugins. In Composer 2.2+ you may need:

"config": { "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true } }

phpcbf is not safe on first run. On a codebase that's never been sniffed, phpcbf can move braces, split lines, and reformat docblocks across hundreds of files. Run phpcs first, review the diff scale, then phpcbf a single directory at a time and commit in reviewable chunks.

Conflict with Pint / php-cs-fixer. These tools have overlapping but non-identical opinions. Running both in CI is a recipe for "Pint fixes it, PHPCS flags it, Pint fixes it again" churn. Pick one as the formatter (phpcbf or Pint) and the other as read-only, or drop one entirely.

Exit codes break CI silently. phpcs exits 1 on violations and 3 on internal errors (like a bad ruleset ref). A CI step that "fails mysteriously" is often a ruleset path problem, not a style problem — check the stderr output, not just the exit code.

Caching and speed. For larger apps, enable the parallel run (<arg name="parallel" value="8"/>) and PHPCS's internal cache:

<arg name="cache" value=".phpcs-cache"/>

Add .phpcs-cache to .gitignore. Cache invalidation issues show up as rules that "stopped working" after a ruleset change — phpcs --cache=path --no-cache clears it.

Line length and Laravel style. Generic.Files.LineLength is notorious — Laravel's own code frequently exceeds 80 chars in fluent chains. Many teams exclude it on day one; check the actual default limit in the ruleset before chasing warnings.

Extension points. You rarely need to fork the package. phpcs.xml supports <rule ref="Laravel"/> plus <exclude> per sniff, and <config name="..." value="..."/> for sniff-specific settings. Only fork if you need to add new sniffs to the standard itself — the ruleset is a thin XML wrapper, so a local copy in phpcs/ is easier to maintain than a fork.

Version pinning. With a 2022-era package, pin a commit or tag in composer.json ("mreduar/laravel-phpcs": "^0.8") so a surprise ruleset update doesn't turn a green build red overnight.