Coding Standard Laravel Package

Getting Started

This package is a preconfigured PHP Coding Standard built on top of PHP_CodeSniffer (PHPCS), Slevomat Coding Standard, and Doctrine Coding Standard. To start using it:

1. Require it as a dev dependency in your project:

   composer require --dev wyrihaximus/coding-standard
   

2. Add PHPCS configuration (e.g., in phpcs.xml.dist) that extends the standard:

   <?xml version="1.0"?>
   <ruleset name="MyProjectStandard">
       <file>src</file>
       <file>tests</file>
       <rule ref="WyriHaximus"/>
   </ruleset>
   

3. Run linting with:

   ./vendor/bin/phpcs
   

   Or install automatically with PHPCSFixer/PHPCBF (optional, but common workflow):

   ./vendor/bin/phpcbf
   

The default configuration targets PHP 8.4+, and leverages modern coding standards (Slevomat + Doctrine) with a focus on consistency, static analysis safety, and PHP’s latest features.

Implementation Patterns

• Inherit & Extend: Avoid copying config files. Use <rule ref="WyriHaximus"/> and override only what you need (e.g., specific sniff settings inside <rule>)
• CI Integration: Wrap PHPCS in Composer scripts and use in GitHub Actions (example phpcs.yml):

  - name: Run PHPCS
    run: vendor/bin/phpcs -n
  

• IDE Setup: Configure your IDE ( PhpStorm, VS Code) to use vendor/bin/phpcs and phpcs.xml.dist as the config.
• Auto-fix Workflow: Pair with phpcbf — add scripts to composer.json:

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

• Monorepo Usage: Define one central phpcs.xml.dist at root, and reference subdirectories via <file> elements; avoid per-package duplication.

Gotchas and Tips

• Breaking changes in minor versions: The package frequently bumps its dependencies (e.g., PHPCS v3 → v4, Slevomat ^8.x), and sometimes changes sniff behavior. Check release notes (especially PR titles in releases) before updating.
• PHP version mismatch: The coding standard enforces PHP 8.4+ in recent releases (v2.21+). Using it with older PHP versions (e.g., 8.1) may cause PHPCS to skip sniffs or throw errors. Ensure your php CLI matches your target.
• No built-in ignore list: Unlike many standards, this package doesn’t ship a default phpcs.xml; you must define your own. Start from vendor/wyrihaximus/coding-standard/phpcs.xml.dist (if present) or build from scratch — but do not copy it verbatim as it’s subject to change.
• Sniff conflicts: Because it aggregates Slevomat + Doctrine standards, some sniffs may overlap (e.g., SlevomatCodingStandard.TypeHints.ReturnTypeHint vs Doctrine\ORM\Sniffs\Annotations\ReturnTypeHintSniff). Use <exclude> tags to resolve duplicates:

  <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
      <exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingAnyTypeHint"/>
  </rule>
  

• Customizing rules: Use <severity>, <exclude>, and <properties> in your phpcs.xml — the base ruleset is opinionated and strict (e.g., forbids @api, enforces declare(strict_types=1)).
• Silent failures: PHPCS may silently skip files if targetVersion isn’t set correctly — explicitly set <arg name="basepath" value="."/> and <arg name="encoding" value="utf-8"/> if issues arise.