Style Checker Laravel Package

Getting Started

1. Confirm what you're actually installing. The package is archived (0 stars, 0 dependents), so treat it as a static artifact, not a maintained dependency. Before wiring it in, open the repo and check three things:

• The composer.json require block — specifically the squizlabs/php_codesniffer (or phpcsstandards/php_codesniffer) constraint. This is what will fight with your project.
• Whether it depends on dealerdirect/phpcodesniffer-composer-installer. If yes, the standard auto-registers; if no, you'll need installed_paths.
• Where the ruleset lives — almost always a ruleset.xml at the repo root or under src/. That file is the package. Everything else is packaging.

2. Install as a dev dependency and pin it.

composer require --dev movingimage/style-checker

Because it's archived, commit the composer.lock immediately and pin the exact version ("movingimage/style-checker": "1.2.3"). Do not use a ^ constraint — there will be no patch releases to fix breakage.

3. Find the standard's name. Locate the installed ruleset:

ls vendor/movingimage/style-checker
grep -R '<ruleset name=' vendor/movingimage/style-checker --include=ruleset.xml

The name attribute in that tag (or the value used in the README's ref=) is what you reference. If dealerdirect is installed, vendor/bin/phpcs -i will list it among the installed standards.

4. Create your project ruleset. Your own phpcs.xml should be the source of truth and simply include the vendor ruleset:

<?xml version="1.0"?>
<ruleset name="MyProject">
    <description>Project coding standard.</description>

    <!-- The vendor standard -->
    <rule ref="MovingImage"/>

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

    <arg name="extensions" value="php"/>
    <arg name="colors"/>
    <arg name="cache" value=".phpcs-cache"/>
</ruleset>

If the standard did not auto-register, point PHPCS at the vendor path instead:

vendor/bin/phpcs --config-set installed_paths vendor/movingimage/style-checker

5. First use case — run it on one file, not the whole repo.

vendor/bin/phpcs --standard=phpcs.xml src/Example.php
vendor/bin/phpcbf --standard=phpcs.xml src/Example.php   # auto-fix

Running phpcbf on a single small file first tells you how much of the standard is auto-fixable before you drown in diffs across the codebase.

Implementation Patterns

Composer scripts as the entry point. Give the team two memorable commands and let nobody invoke phpcs directly:

"scripts": {
    "cs:check": "phpcs --standard=phpcs.xml",
    "cs:fix":   "phpcbf --standard=phpcs.xml || true"
}

The || true on fix matters: phpcbf exits non-zero when it fixed something, which looks like a failure in a script chain.

CI as a blocking gate, fix as a developer convenience. Run cs:check in CI and fail the build; run cs:fix locally on save or pre-commit. The pattern that ages best:

- name: Coding standard
  run: vendor/bin/phpcs --standard=phpcs.xml --report=full --cache

--cache is essential once the ruleset is broad — it cuts a multi-thousand-file run to seconds on subsequent invocations. Cache the .phpcs-cache file between CI runs keyed on the lockfile hash.

Gradual adoption via exclude-pattern. You will not get a legacy codebase to pass on day one. Scope it:

<exclude-pattern>src/Legacy/*</exclude-pattern>
<exclude-pattern>database/migrations/*</exclude-pattern>
<exclude-pattern>*/generated/*</exclude-pattern>

Then shrink the exclusion list sprint by sprint. Alternative: restrict <file> to one directory at a time and add directories as they're cleaned.

Per-directory overrides. A separate tests/phpcs.xml that includes the base ruleset and relaxes specific sniffs is cleaner than a pile of phpcs:ignore comments:

<!-- tests/phpcs.xml -->
<ruleset name="Tests">
    <rule ref="./phpcs.xml"/>
    <rule ref="Squiz.Commenting.FunctionComment">
        <severity>0</severity>
    </rule>
</ruleset>

Pre-commit integration. If you use GrumPHP or CaptainHook, wrap the same phpcs --standard=phpcs.xml command and pass the staged file list through -- so only changed files are checked. Keeping the command identical between CI, hooks, and local scripts is the whole point — divergent invocations are how "works on my machine" starts.

Editor integration. Point the PHPCS plugin at the project binary (vendor/bin/phpcs) and the project phpcs.xml, not a global install. With a custom standard this is the single most common misconfiguration: the editor silently uses the default PSR-12 standard and flags nothing.

Do not run it alongside php-cs-fixer. Both rewrite files. If you already use php-cs-fixer, either port the relevant rules to the fixer and use phpcs only as a checker, or drop one entirely. Running phpcbf and php-cs-fixer fix in sequence produces churn and, occasionally, conflicting transforms.

Gotchas and Tips

The archive status is the real gotcha. Concretely, this means:

• The PHPCS constraint in its composer.json will eventually be unsatisfiable as your toolchain upgrades. Expect to either constrain your PHPCS version or fork the ruleset.
• No fixes for sniffs that break on newer PHP syntax (enums, readonly properties, first-class callables, property hooks). Older rulesets frequently emit false positives on these.
• The pragmatic play: copy vendor/movingimage/style-checker/ruleset.xml into your repo as phpcs-movingimage.xml, delete the dependency, and reference it locally. It's one file, it's static anyway, and it removes an abandoned transitive dependency from your lockfile. Keep the copyright header and note provenance.

installed_paths is absolute-path-hostile. --config-set writes absolute paths into vendor/squizlabs/php_codesniffer/CodeSniffer.conf, which breaks across machines and CI checkouts. Prefer dealerdirect/phpcodesniffer-composer-installer (and accept the Composer 2.2+ allow-plugins prompt in composer.json), or use the direct path reference in phpcs.xml.

Composer 2.2+ silently skips the installer plugin. If the standard doesn't appear in phpcs -i, this is almost always why. Add:

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

Use -s to expose sniff codes before suppressing. The single most useful debugging flag:

vendor/bin/phpcs -s --standard=phpcs.xml src/Foo.php

It appends (Standard.Category.SniffName) to each message. Suppress by that code, never by message text:

// phpcs:ignore Generic.Arrays.DisallowShortArraySyntax.Found

Blanket phpcs:disable at the top of a file is a smell — it hides new violations added later in that file.

Tune severity instead of deleting rules. <severity>0</severity> disables a sniff; <severity>5</severity> (against the default threshold of 5) makes it advisory. Using severity keeps the rule documented in the ruleset for future readers, which a deleted block does not.

phpcbf won't fix everything, and sometimes makes it worse. Run it, then git diff and actually read the result. Some of the more aggressive formatting sniffs in older rulesets reflow multi-line signatures into unreadable single lines. If a sniff's fixer output is unacceptable, disable the sniff and keep the check off rather than fighting the auto-fixer on every commit.

Watch the interaction with --cache. The cache is keyed on file contents and ruleset config; if you change phpcs.xml and see stale results, delete .phpcs-cache. Also make sure it's gitignored.

Exit codes. phpcs: 0 clean, 1 violations found, 2 processing error (usually a broken ruleset path or a missing standard — not a style failure). If CI fails with 2, look at the ruleset reference first, not the code under test.