Coding Standard Laravel Package

Getting Started

Start by installing doctrine/coding-standard via Composer — it’s a PHPCS ruleset, so you’ll also need PHP_CodeSniffer (squizlabs/php_codesniffer). Run:

composer require --dev doctrine/coding-standard squizlabs/php_codesniffer

Then configure PHPCS to use Doctrine’s standard:

./vendor/bin/phpcs -i
# Look for "Doctrine" in the list of installed standards
./vendor/bin/phpcs --standard=Doctrine path/to/src

For CI or local use, set up a phpcs.xml config file to reuse defaults (it auto-extends doctrine/coding-standard via the phpcs.xml.dist included in the package — just reference it). The first use case is running static analysis on your codebase to catch style deviations — especially before merging PRs.

Implementation Patterns

• Project-wide enforcement: Define <rule ref="Doctrine"/> in phpcs.xml, optionally adding custom exclusions or overloads (e.g., // @phpcs:ignore Doctrine.Files.ClassFileName for legacy files).
• CI integration: Use it with GitHub Actions or Git hooks (pre-commit) to fail builds on style violations:

  - run: ./vendor/bin/phpcs --standard=Doctrine --warning-severity=0 src/
  

• Autofix workflow: Combine with PHPCBF for quick fixes: ./vendor/bin/phpcbf --standard=Doctrine src/
• IDE integration: Configure PHP_CodeSniffer in PhpStorm or VS Code (PHP Sniffer extension) to show inline warnings using Doctrine rules.
• Gradual adoption: Run on specific directories first (e.g., src/Entity/), then expand to tests/ or entire codebase. Use --extensions=php and --ignore-annotations strategically during rollout.

Gotchas and Tips

• PHPCS v4 requirement: Starting with v14.0.0, Doctrine CS requires php_codesniffer ^4. Avoid conflicts by pinning versions or using dealerdirect/phpcodesniffer-composer-installer to auto-register the ruleset.
• Slevomat CS dependency: This package is a ruleset built on top of slevomat/coding-standard. Understand its core sniffs (e.g., SlevomatCodingStandard.TypeHints.*, SlevomatCodingStandard.ControlStructures.*) to debug failures — Doctrine often extends or tunes them.
• Exhaustive reporting: Always use --report-full or --report-summary to see sniff codes (e.g., Doctrine.Files.UnsafeClass) — crucial for targeted ignore comments like // @phpcs:ignore Doctrine.Files.UnsafeClass.
• PHP 8+ compatibility: v11+ introducedsniffs for attributes, constructor property promotion, and match expressions — ensure your project’s minimum PHP version matches. Use phpcs -p with --cache to speed up repeated runs.
• Troubleshooting false positives: Use --sniffs=... to isolate problematic sniffs. For stubborn issues (e.g., BlankLineBetweenProperties), check if your PHPDoc/attribute annotations conflict with strict spacing rules — Doctrine enforces 1 blank line between properties only if docblocks exist.
• Extension points: Override sniffs by defining your own <rule> blocks in phpcs.xml, e.g., relax SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint if targeting legacy code. Also, consider phpcs.xml.dist for project defaults while allowing local phpcs.xml overrides.