Coding Standard Laravel Package

Getting Started

var-lab/coding-standard is a shared PHP_CodeSniffer ruleset (with Symfony-flavoured conventions) that you pull in as a require-dev dependency so every project in the org lints against the same rules. Treat it as infrastructure, not application code.

1. Wire up the private repository. Because the package lives on git.var-lab.com, add the VCS/repo entry to your project's composer.json once (or rely on a global ~/.composer/config.json / COMPOSER_AUTH):

{
  "repositories": [
    { "type": "vcs", "url": "https://git.var-lab.com/dev-tools/coding-standard-php.git" }
  ]
}

2. Install as a dev dependency:

composer require --dev var-lab/coding-standard

3. Confirm the standard is registered. PHPCS discovers installed standards by scanning vendor/*/*/ruleset.xml (or the type: phpcs-standard package convention). Verify with:

vendor/bin/phpcs -i
# Installed coding standards: PSR12, Symfony, VarLab, ...

If VarLab (or whatever the ruleset's <ruleset name="..."> says) doesn't appear, the install didn't register — check vendor/var-lab/coding-standard/ actually exists and contains a ruleset.xml.

4. Look at the ruleset first. Open vendor/var-lab/coding-standard/ruleset.xml before writing any config. It tells you which base standards are extended (typically PSR-12 + Symfony + Slevomat), what's excluded, and the exact standard name to reference. This is the file that answers "why is this sniff firing?"

5. First run on a single directory to see the blast radius:

vendor/bin/phpcs --standard=VarLab src/

Don't run it repo-wide on day one against a legacy codebase — you'll get thousands of violations and give up. Start with src/, look at --report=summary to triage by sniff, then expand.

Implementation Patterns

Project-level phpcs.xml extending the shared standard. This is the normal integration — you rarely pass --standard on the CLI; you commit a config so CI and editors agree:

<?xml version="1.0"?>
<ruleset name="MyProject">
    <description>Project rules, extends var-lab coding standard.</description>

    <!-- Reference the vendor ruleset by name, not path -->
    <rule ref="VarLab"/>

    <!-- Project-specific relaxations -->
    <rule ref="Generic.Files.LineLength">
        <properties>
            <property name="lineLimit" value="120"/>
        </properties>
    </rule>

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

    <exclude-pattern>*/var/*</exclude-pattern>
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/migrations/*</exclude-pattern>
</ruleset>

Then vendor/bin/phpcs with no args picks up phpcs.xml automatically. Note the <rule ref="VarLab"/> — this only works if the standard is discovered; otherwise use the absolute path to the ruleset file (see Gotchas).

Composer scripts so nobody memorises flags:

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

composer lint / composer lint:fix becomes the team vocabulary.

CI gate (GitHub Actions example):

- name: Coding standard
  run: composer lint:ci

Emit checkstyle or full reports — many CI systems render checkstyle inline on the PR, which is far more useful than a wall of console output.

Autofix loop before you commit. The standard is designed so phpcbf handles the mechanical stuff (import order, spacing, trailing commas, declare(strict_types=1) insertion). The everyday workflow is:

composer lint:fix   # fix what's fixable
composer lint       # see what remains — these need human decisions

Never trust phpcbf alone; always re-run phpcs after, because some sniffs conflict and fixers can oscillate.

Pre-commit hook. Wire PHPCS into captainhook or a .git/hooks/pre-commit shim so violations never reach CI. Only lint staged files for speed:

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

Diff-only during migration. For a legacy repo you can't clean all at once, use the changed-lines report to ratchet rather than rewrite:

vendor/bin/phpcs --report=diff src/ > phpcs.patch

Apply phpcs.patch per PR so only touched files get cleaned — this is the gradual-adoption pattern that actually lands.

Baseline. PHPCS 3.7+ supports --generate-baseline (via phpcs-baseline or newer core options depending on version). Generate a baseline of existing violations, commit it, and new code is held to the full standard while old debt is frozen. Regenerate occasionally as you pay down debt.

Editor parity. In PhpStorm, point Settings → PHP → Quality Tools → PHP_CodeSniffer at vendor/bin/phpcs and set the standard to your project phpcs.xml (not the global "VarLab" name — use the project config so overrides apply). Enable "PHP Code Sniffer validation" on save. If the editor disagrees with CLI, the editor is almost always pointed at a different config.

Gotchas and Tips

The standard's name is load-bearing. --standard=VarLab and <rule ref="VarLab"/> require PHPCS to have installed the standard, which depends on the ruleset.xml's name attribute matching. If you get "the coding standard VarLab is not installed", don't guess the name — read vendor/var-lab/coding-standard/ruleset.xml line 2, then run vendor/bin/phpcs -i to confirm. When in doubt, reference the ruleset by path (<rule ref="./vendor/var-lab/coding-standard/ruleset.xml"/>) which bypasses discovery entirely. Case matters on Linux CI even if it works on macOS.

Private repo auth will bite you in CI. Local dev works via SSH key; the CI runner may not have one. Either set COMPOSER_AUTH with a deploy token, configure a GitLab COMPOSER_REPOSITORIES/CI job token, or mirror the package. The failure mode is a composer install error, not a PHPCS error, so it looks unrelated.

Cache lies after upgrades. PHPCS caches results by file mtime. After bumping the standard, stale cache can hide new violations or report fixed ones. vendor/bin/phpcs --cache is a nice speedup in CI, but rm -rf .phpcs-cache (or --cache=false) whenever you change the ruleset or upgrade the package.

phpcs.xml beats CLI flags in unexpected ways. If a config file exists, PHPCS reads it and ignores many CLI defaults. phpcs --standard=PSR12 will still be merged with the config's <rule> elements — it doesn't override cleanly. To force a one-off, either edit the config or pass --standard= with an explicit path.

Exclusions belong in config, not your head. Generated code (var/, vendor/, Doctrine proxies), migrations, and fixtures will drown out real findings. Add <exclude-pattern> entries once, in phpcs.xml, so all tools (CLI, editor, CI) inherit them. Forgetting vendor/ is a classic first-run mistake that produces hundreds of thousands of violations.

phpcbf can break code, not just fail to fix it. Most rules are safe, but ordering-sensitive sniffs (unused imports, fully-qualified name shortening) occasionally rewrite in ways that change semantics on edge cases (string class names, annotations). Always run phpcbf on a clean working tree so git diff shows exactly what it touched, and never let a pre-commit hook phpcbf and auto-stage without review during adoption.

Severity, not deletion, for one weird rule. Rather than deleting a sniff you disagree with, lower its severity in your phpcs.xml:

<rule ref="SlevomatCodingStandard.Functions.StrictCall">
    <severity>0</severity>
</rule>

Use type="warning" for aspirational rules, type="error" for must-fix. Warnings don't fail the build by default — a good way to surface style suggestions without blocking PRs.

Extension point: custom-rules/. If the package ships project-specific sniffs, they're registered in the ruleset and live under the package's Sniffs/ namespace. You don't sub-class them per project — instead, propose changes upstream, because fighting a shared standard locally defeats the point. If you must diverge, do it in phpcs.xml exclusions, not by forking.

Editors report differently than CI — trust CI. PhpStorm only surfaces sniffs for open files and can lag behind config changes. When a PR fails but your editor is green, run vendor/bin/phpcs locally before blaming the standard. This is almost always stale editor config, not a bug in the package.

Pin the version. A shared standard that auto-updates on composer update will one day turn a green branch red. Pin a minor version ("var-lab/coding-standard": "~2.1") and upgrade deliberately, running composer lint on a branch first so you see the new violations in isolation.