Getting Started

Minimal Steps

Install the Package Require the package in your Laravel project:
```
composer require --dev phpcq/coding-standard
```

First Run with PHP_CodeSniffer Use the provided ruleset directly with phpcs:

vendor/bin/phpcs --standard=vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml src/

First Run with PHPMD Run static analysis checks:

vendor/bin/phpmd src/ text vendor/phpcq/coding-standard/phpmd/ruleset.xml

Quick Integration with Laravel Add a Composer script for easy access:

"scripts": {
    "cs-fix": "phpcs --standard=vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml --report=full src/",
    "cs-fix:fix": "phpcbf --standard=vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml src/"
}

Run with:

composer cs-fix

Where to Look First
- Ruleset XML: vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml
- Documentation: Check the PHP_CodeSniffer docs for rule explanations.
- Laravel-Specific Adjustments: Focus on app/ and routes/ directories initially.

Implementation Patterns

Daily Developer Workflows

Local Development
- Run checks before committing:
```
composer cs-fix
```
- Use IDE integration (e.g., PHPStorm’s PHP_CodeSniffer plugin) for real-time feedback.
Pull Requests
- Add a CI check in .github/workflows/phpcs.yml:
```
- name: PHP_CodeSniffer
  run: composer cs-fix
```
- Require approval only if checks pass.

Team Standards

Document exceptions in CONTRIBUTING.md:

## Coding Standards
- Run `composer cs-fix` before PRs.
- Exceptions: `app/Providers/` may have dynamic properties.

Automated Fixes
- Use phpcbf (PHP_CodeSniffer’s fixer) for auto-correction:
```
composer cs-fix:fix
```

Laravel-Specific Patterns

Excluding Laravel Directories Override the ruleset to exclude Laravel-specific paths:

<!-- phpcs.ruleset.xml -->
<rule ref="PhpCodeQuality">
    <exclude name="App\Providers" />
    <exclude name="routes" />
    <exclude name="bootstrap/cache" />
</rule>

Laravel Naming Conventions Enforce Laravel’s App\ namespace prefix:

<rule ref="PhpCodeQuality">
    <arg name="namespacePrefix" value="App\" />
</rule>

Integration with Laravel Mix Add checks to postcss or webpack.mix.js build scripts:

mix.postCss('resources/css/app.css', 'public/css', [
    require('postcss-import'),
    require('tailwindcss')
])
.then(() => {
    require('child_process').execSync('composer cs-fix');
});

Testing Workflows Skip checks for tests/ in CI but enforce in local development:

# .github/workflows/phpcs.yml
jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - run: composer cs-fix --ignore=tests/

CI/CD Patterns

GitHub Actions

name: PHP_CodeSniffer
on: [push, pull_request]
jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install --dev
      - run: vendor/bin/phpcs --standard=vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml src/

GitLab CI

phpcs:
  stage: test
  script:
    - composer cs-fix
  only:
    - merge_requests

Parallel Checks Split checks across files/directories for faster CI:

- name: PHPCS (App)
  run: vendor/bin/phpcs src/App/
- name: PHPCS (Routes)
  run: vendor/bin/phpcs src/routes/

Gotchas and Tips

Common Pitfalls

False Positives in Laravel

Dynamic Properties: Laravel uses dynamic properties (e.g., Model::$relation). Exclude or suppress:

<rule ref="Generic.Files.LineEndings" />
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace">
    <exclude name="App\Models" />
</rule>

Magic Methods: Laravel’s __call, __get, etc., may trigger rules. Add exceptions:

<rule ref="Squiz.Commenting.InlineComment">
    <exclude name="App\Concerns" />
</rule>

Performance in CI
- Exclude Large Files: Skip tests/, storage/, and vendor/:
```
vendor/bin/phpcs --ignore=tests/,storage/,vendor/ src/
```
- Cache Results: Use tools like phpcs-cache to avoid rescanning unchanged files.

Rule Conflicts

PSR-12 vs. PhpCodeQuality: Some rules may conflict. Audit with:

vendor/bin/phpcs --standard=PSR12 src/ | head -n 20
vendor/bin/phpcs --standard=PhpCodeQuality src/ | head -n 20

Merge Rulesets: Combine with PSR-12 if needed:

<config name="standard" value="PSR12,PhpCodeQuality" />

IDE Integration Issues
- PHPStorm: Ensure the PHP_CodeSniffer plugin is configured to use the correct ruleset path:
```
vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml
```
- VSCode: Use the PHP Intelephense extension with phpcs configured in settings.json:
```
"intelephense.phpcsStandard": "vendor/phpcq/coding-standard/phpcs/PhpCodeQuality/ruleset.xml"
```

Debugging Tips

Verbose Output Run with --report=full for detailed violations:

vendor/bin/phpcs --standard=PhpCodeQuality --report=full src/

Isolate Violations Check specific files or directories:
```
vendor/bin/phpcs src/App/Http/Controllers/
```
Temporary Exclusions Use comments to suppress specific violations:
```
// phpcs:ignore Generic.Files.LineEndings
```
Update Rulesets Monitor for updates and test before applying:
```
composer update phpcq/coding-standard --dev
```

Extension Points

Custom Rules Extend the ruleset by adding new rules:

<rule ref="PhpCodeQuality">
    <file>src/App/Rules/LaravelSpecificRule.php</file>
</rule>

PHPMD Custom Rules Add PHPMD rules for Laravel-specific smells:

<rule ref="phpmd/rules/naming.xml">
    <exclude name="src/App/Providers" />
</rule>

Composer Scripts Create reusable scripts in composer.json:

"scripts": {
    "cs-check": "vendor/bin/phpcs --standard=PhpCodeQuality src/",
    "cs-check:fix": "vendor/bin/phpcbf --standard=PhpCodeQuality src/",
    "cs-check:ci": "vendor/bin/phpcs --standard=PhpCodeQuality --ignore=tests/ src/"
}

Environment-Specific Configs Use different rulesets for local vs. CI:

# Local (strict)
vendor/bin/phpcs --standard=PhpCodeQuality src/

# CI (lenient)
vendor/bin/phpcs --standard=PhpCodeQuality --ignore=tests/ src/

Laravel-Specific Quirks

Facade Usage Laravel’s facades (e.g., Route::get()) may trigger unused-function calls. Exclude:
```
<rule ref="UnusedFunction">
    <exclude name="src/routes" />
</rule>
```
Blade Templates Exclude Blade files from phpcs

Coding Standard Laravel Package