Php Coding Standard Laravel Package

Getting Started

This is a PHP_CodeSniffer ruleset, not a library — there is no runtime API to call. You "use" it by pointing phpcs/phpcbf at the standard it registers.

1. Install the tool and the ruleset together:

composer require --dev squizlabs/php_codesniffer webtoolshealth/php-coding-standard

2. Make PHPCS aware of the standard. This is the step people miss. PHPCS only discovers standards installed under vendor/ if the Composer installer plugin is present:

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

Then confirm registration:

vendor/bin/phpcs -i
# The installed coding standards are PSR12, WebtoolsHealth, ...

3. Create phpcs.xml.dist at the repo root (see next section) referencing the standard by name.

4. First run:

vendor/bin/phpcs          # uses phpcs.xml.dist automatically
vendor/bin/phpcbf         # auto-fix what is fixable

Where to look first: open vendor/webtoolshealth/php-coding-standard/ruleset.xml. That single file is the entire product — it lists which upstream sniffs (PSR12, Slevomat, Generic, Squiz, etc.) are enabled, their severities, and any custom sniffs shipped in the package. Read it before adopting anything; the standard name you pass to --standard is the <ruleset name="..."> value.

First real use case: run it read-only against one directory before wiring it into CI, so you can gauge the noise level:

vendor/bin/phpcs --standard=WebtoolsHealth --report=summary app/

Implementation Patterns

Canonical phpcs.xml.dist. Treat the vendor ruleset as a base and own a project ruleset that includes it — never edit files in vendor/:

<?xml version="1.0"?>
<ruleset name="Project">
    <description>Project standard built on WebtoolsHealth.</description>

    <file>app</file>
    <file>tests</file>

    <arg name="extensions" value="php"/>
    <arg name="colors"/>
    <arg value="sp"/>
    <arg name="parallel" value="8"/>
    <arg name="cache" value=".phpcs.cache"/>

    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/storage/*</exclude-pattern>

    <!-- Pull in the whole WT Health standard. -->
    <rule ref="WebtoolsHealth"/>

    <!-- Then narrow or relax per path. -->
    <rule ref="WebtoolsHealth">
        <exclude name="Generic.Files.LineLength"/>
    </rule>

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

Overriding a single sniff is done by re-declaring it after the include — PHPCS merges in document order, so the later block wins.

Composer scripts keep the entry points discoverable and identical in CI and locally:

"scripts": {
    "lint": "phpcs",
    "lint:fix": "phpcbf",
    "lint:ci": "phpcs --report=checkstyle --report-file=build/phpcs.xml"
}

CI (GitHub Actions) pattern. Fix first, then fail the build on anything remaining, and cache the result:

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.1'
    tools: cs2pr
- run: composer install --no-interaction --prefer-dist
- run: vendor/bin/phpcbf || true
- run: vendor/bin/phpcs -q --report=checkstyle | cs2pr

cs2pr turns the Checkstyle report into inline PR annotations — far more useful than a wall of terminal output. Note the || true on phpcbf: it exits non-zero whenever it changed something, which is expected, not a failure.

IDE integration. In PhpStorm, set Settings → PHP → Quality Tools → PHP_CodeSniffer to vendor/bin/phpcs, then choose the standard from the dropdown (it will appear because Composer registered it). In VS Code, shevaua.phpcs with "phpcs.standard": "WebtoolsHealth". Both invoke the same binary, so behaviour matches CI exactly.

Pre-commit gate with a staged-files-only run, so hooks stay under a second:

vendor/bin/phpcs --standard=WebtoolsHealth $(git diff --cached --name-only --diff-filter=ACM -- '*.php')

Legacy codebase onboarding. Don't try to make a ten-year-old app pass on day one. Either generate a baseline with a third-party tool (e.g. phpcs-baseline, which writes a ruleset excluding currently-failing files) or scope <file> to new directories only and expand it every sprint. The archived status of this package makes the baseline approach especially attractive — you get the rules exactly where they matter with no mass rewrite.

Per-directory severity. Drops of severity beat disabling a sniff outright, because violations still show up as warnings in the report:

<rule ref="WebtoolsHealth">
    <severity>0</severity>
</rule>
<rule ref="WebtoolsHealth">
    <include-pattern>*/app/Domain/*</include-pattern>
</rule>

Gotchas and Tips

The package is archived (last release June 2021). There will be no compatibility fixes, no new-PHP-syntax support, and no security triage. Two consequences you must plan around: (a) pin it to an exact version — "webtoolshealth/php-coding-standard": "1.2.3" — because a floating constraint can never be meaningfully satisfied by future work; (b) if you rely on it long-term, fork the repo and vendor the ruleset.xml into your own project's phpcs.xml.dist as a plain reference. The ruleset is XML, so extracting it is trivial and removes both the dependency and the abandonment risk.

Nothing is registered without the installer plugin. The single most common failure is phpcs -i not listing the standard after a successful composer install. Either add dealerdirect/phpcodesniffer-composer-installer, or bypass discovery entirely by pointing at the file:

vendor/bin/phpcs --standard=vendor/webtoolshealth/php-coding-standard/ruleset.xml app/

The path form always works and is a useful fallback when Composer plugins are disabled (--no-plugins in CI is a frequent culprit).

Old sniffs versus modern syntax. A 2021 ruleset will often contain sniffs and testVersion settings that predate PHP 8 enums, readonly properties, first-class callables, and intersection types. Symptoms look like nonsense errors — "expected a class name" on valid readonly code, or whitespace complaints inside match arms. Diagnose with the sniff code visible before assuming your code is wrong:

vendor/bin/phpcs -s app/Foo.php     # -s prints the sniff code, e.g. Squiz.WhiteSpace.X.Found

Then disable that specific sniff in your project ruleset rather than abandoning the whole standard.

Use -e to audit what you're actually adopting. vendor/bin/phpcs -e --standard=WebtoolsHealth prints the full expanded sniff list. This is how you discover whether it bundles PHPCompatibility, Slevomat, or doctrine coding standard transitively — useful for judging overlap with tools you already run.

Autofix and code review conflict. phpcbf will rewrite use statement ordering, alignment, and comment spacing. If you run it on a branch that's also under review, you get a merge-conflict-heavy diff that hides real changes. Fix formatting in a dedicated commit before opening a feature branch, never mixed in with logic.

Cache invalidation. --cache (or <arg name="cache">) is a large speedup on big repos, but the cache is keyed to the ruleset contents. If you edit phpcs.xml.dist and results look stale, delete .phpcs.cache. In CI, either persist the cache file between runs or omit the flag entirely.

Reports for humans versus machines. The default full report is unreadable in a terminal at scale. Use --report=summary locally, --report=source to prioritize which sniff you should fix first (it groups violations by rule and says "this one rule accounts for 40% of your problems"), and --report=checkstyle for CI consumption.

Exit codes. phpcs returns 1 for violations, 2 for a processing error (bad standard name, unreadable file, malformed XML). Don't conflate them in CI scripts — a 2 means your configuration is broken, not that your code is dirty. Add -q to suppress progress output so the actual report is visible in logs.

Extension points are limited by design. There is no plugin API — the only lever is XML composition. Anything you cannot express by including/excluding a sniff, changing its severity, setting its <properties>, or scoping via <include-pattern>/<exclude-pattern> requires writing your own sniff class in your project and registering it with <rule ref="./path/to/Sniffs"/>. For a package this small and stale, that is usually the right call: the value is the curated sniff selection, and you can capture it in a fifty-line phpcs.xml.dist and drop the dependency entirely.