Coding Standards Laravel Package

Getting Started

humanmade/coding-standards is a PHP_CodeSniffer (phpcs) ruleset, not a runtime library. Nothing ships to production; the value is a lint gate and an auto-fixer you run locally and in CI.

1. Install as a dev dependency:

   composer require --dev humanmade/coding-standards
   

2. If your install pulls in dealerdirect/phpcodesniffer-composer-installer (it usually does, transitively via WPCS), allow the plugin in composer.json on Composer 2.2+:

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

3. Verify the standard registered itself:

   vendor/bin/phpcs -i
   # should list HumanMade alongside WordPress, WordPress-Extra, PHPCompatibility, etc.
   

4. Drop a minimal phpcs.xml.dist at the project root:

   <?xml version="1.0"?>
   <ruleset name="Project">
     <description>Project coding standard.</description>
     <rule ref="HumanMade"/>
     <file>.</file>
     <exclude-pattern>vendor/*</exclude-pattern>
     <exclude-pattern>node_modules/*</exclude-pattern>
     <exclude-pattern>storage/*</exclude-pattern>
     <config name="testVersion" value="8.1-"/>
   </ruleset>
   

5. First use case: lint one file, fix it, then widen the net.

   vendor/bin/phpcs app/Services/Billing.php
   vendor/bin/phpcbf app/Services/Billing.php
   

Where to look first: open vendor/humanmade/coding-standards/ and read the ruleset XML. It is a thin composition layer over WPCS plus PHPCompatibility, with its own inclusions/exclusions. That file tells you exactly which upstream standards you are inheriting, which is the single most useful thing to know before you start fighting a sniff.

Implementation Patterns

Composer scripts as the entry point. Wire lint into composer.json so nobody memorises flags:

"scripts": {
  "lint": "phpcs",
  "lint:fix": "phpcbf",
  "lint:summary": "phpcs --report=summary"
}

phpcs with no arguments reads phpcs.xml.dist, so the config file is the contract.

Separate fix commits from feature commits. Run phpcbf, review git diff, and commit the mechanical churn on its own. Reviewers cannot read a 400-line whitespace diff mixed with logic.

Incremental adoption on a legacy codebase. Do not enable the whole tree on day one. Either:

• Scope <file> to new directories first, or
• Run phpcs --report=source to rank sniffs by violation count, and exclude the top offenders by sniff rather than by path:

<rule ref="HumanMade">
  <exclude name="WordPress.Files.FileName"/>
</rule>

Per-area rulesets. Themes/plugins/views and PHPUnit tests often want different treatment. Keep the root ruleset authoritative and use <exclude-pattern> for tests/* or template directories, or attach the PHPUnit standard to tests only via a secondary ruleset invoked with --standard.

Editor parity with CI. Point the VS Code phpcs extension at vendor/bin/phpcs and the project phpcs.xml.dist. Editor and CI must use the same binary, same ruleset, and the same PHP binary — a version skew here is the #1 source of "passes locally, fails in CI".

CI job shape. Run lint as a fast, independent job:

- run: composer install --no-progress --prefer-dist
- run: vendor/bin/phpcs --report=checkstyle --report-file=phpcs.xml

Checkstyle output gives you inline PR annotations. Use --parallel=$(nproc) and bump memory_limit for large trees.

Pre-commit hook. Hook phpcs on staged files via GrumPHP, CaptainHook, or a plain .git/hooks/pre-commit. Restrict to changed files (git diff --cached --name-only --diff-filter=ACM | grep '\.php$') so the hook stays sub-second.

Suppression discipline. Prefer // phpcs:ignore Specific.Sniff.Name -- reason at the line level over phpcs:disable blocks. Blanket disables become permanent and invisible; scoped ignores with a reason survive code review.

Extension point. To add house sniffs, create your own standard directory containing a ruleset.xml that does <rule ref="HumanMade"/> plus <rule ref="./MySniffs"/>, and register it in installed_paths (or add the directory via the composer installer's extra). You get HM's baseline plus your own checks without forking the package.

Gotchas and Tips

"The HumanMade standard is not installed." This is almost always the Composer plugin being blocked, or a phpcs binary running outside the project vendor dir (global install, or a CI image with its own phpcs). Check vendor/bin/phpcs -i and vendor/bin/phpcs --config-show for installed_paths.

It is WPCS-derived, so it is WordPress-flavoured. The "modern code" tagline does not remove sniffs about escaping output, nonces, wp_ prefixes, direct DB queries, and i18n text domains. In a Laravel or framework-agnostic codebase you will get noise that has no meaning. Exclude those sniff groups deliberately in phpcs.xml.dist rather than sprinkling ignores.

It is phpcs, not PHP-CS-Fixer — so it does not compose with Pint. If the team runs Laravel Pint (PHP-CS-Fixer under the hood), the two tools will reformat each other's output indefinitely. Pick one as the formatter, and if you keep HM, run Pint only for the rules HM does not cover — or drop one. Do not put both in the same pre-commit hook.

Pin your versions. This ruleset's results are a function of the WPCS and PHPCompatibility versions it pulls in. A composer update that bumps WPCS can turn a green build red with zero code changes. Pin to exact versions (or at least ~) and treat standard upgrades as their own PR with a reviewed diff.

Set testVersion explicitly. PHPCompatibility's testVersion config defaults can both miss and invent problems. Set the minimum (and maximum, if relevant) PHP your app actually supports: <config name="testVersion" value="8.1-8.3"/>.

phpcbf is not always safe. It will happily reflow whitespace inside heredocs, blob-like strings, and mixed PHP/HTML templates. Exclude resources/views, email templates, and generated files from fixing, and always review the diff. Never run phpcbf on uncommitted work.

Mixed PHP/HTML files are noisy. Sniffs that expect pure PHP structure misfire in templates. Constrain with --extensions=php and/or <exclude-pattern> for view directories.

Parse errors mean stale tools, not bad code. A "syntax error" on a modern PHP construct (enums, readonly properties, first-class callables) means the bundled PHP_CodeSniffer/PHPCompatibility is older than your language level. Upgrade the tooling; do not disable the sniff.

Large trees are slow and memory-hungry. --parallel is only available on newer phpcs; on older versions, split the run by directory in CI and raise memory_limit. Do not let lint become the slowest job in the pipeline — developers route around it.

Report format matters for triage. --report=summary and --report=source tell you which sniffs are burning you; --report=full on a legacy file is unreadable. Use source reports to decide what to exclude and what to actually fix.

Severity is a blunt tool but useful. <rule ref="X"><severity>0</severity></rule> silences a sniff without deleting the config line, which documents intent and makes re-enabling a one-character change. Better than deleting rules you intend to restore later.