Getting Started

Minimal Setup for Laravel Developers

Install the Package Add to composer.json under require-dev:
```
composer require --dev wdes/coding-standard
```
Remove existing squizlabs/php_codesniffer if present (this package bundles its own).
Configure phpcs.xml Create phpcs.xml in your project root with the provided template, ensuring:
- <file>.</file> or specify paths like src/, app/.
- Exclude vendor/, node_modules/, and tmp/ by default.
- Enable colors (<arg name="colors"/>) for better CLI output.
First Run Check code quality:
```
./vendor/bin/phpcs
```
Auto-fix issues:
```
./vendor/bin/phpcbf
```

CI/CD Integration Add to .github/workflows/php.yml (example):

- name: Run PHPCS
  run: ./vendor/bin/phpcs --standard=Wdes --colors

First Use Case: Onboarding New Developers

Goal: Ensure new hires adhere to team standards without manual reviews.
Workflow:
1. Clone the repo and run composer install.
2. Execute ./vendor/bin/phpcs to see violations.
3. Use phpcbf to auto-fix common issues (e.g., trailing commas, alignment).
4. Commit fixes with a note like Fix PHPCS violations (Wdes standard).

Implementation Patterns

Daily Workflows

Pre-Commit Hooks Use phpcbf in a hook to auto-fix issues before commits:

composer require --dev laravel-pint
./vendor/bin/phpcbf --standard=Wdes

Laravel-Specific Adjustments

Exclude Laravel-generated files (e.g., migrations, cached views):

<exclude-pattern>*/database/*</exclude-pattern>
<exclude-pattern>*/bootstrap/cache/*</exclude-pattern>

Override PSR12 rules for Laravel conventions (e.g., allow @property in docblocks):

<rule ref="PSR12">
    <exclude name="PSR12.Classes.PropertyDeclaration"/>
</rule>

Team-Specific Customizations
- Disable controversial rules (e.g., Arrays.DisallowLongArraySyntax for legacy code):
```
<rule ref="Wdes">
    <exclude name="Generic.Arrays.DisallowLongArraySyntax"/>
</rule>
```
- Lower severity for non-critical rules (e.g., line length):
```
<rule ref="Generic.Files.LineLength">
    <severity>2</severity>
</rule>
```

Integration with Laravel Tools

Combine with pint for formatting:

composer require --dev laravel-pint
./vendor/bin/pint --test
./vendor/bin/phpcs

Use in phpstan.neon for static analysis:

includes:
    - vendor/wdes/coding-standard/ruleset.xml

Advanced Patterns

Parallel Linting Split phpcs runs by directory in CI to save time:

./vendor/bin/phpcs app/ --parallel=4
./vendor/bin/phpcs src/ --parallel=4

Custom Rule Extensions Extend the standard by creating a child ruleset (e.g., laravel.xml):

<ruleset>
    <rule ref="Wdes"/>
    <rule ref="PSR12">
        <exclude name="PSR12.Namespaces.NoUnusedUses"/>
    </rule>
</ruleset>

GitHub Actions Template Reusable workflow for PHPCS + PHPStan:

jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: ./vendor/bin/phpcs --standard=Wdes --colors --error-severity=5

Gotchas and Tips

Common Pitfalls

PHP Version Mismatches
- PHP <5.4: Disable Generic.Arrays.DisallowLongArraySyntax (short array syntax [$a, $b]).
- PHP <7.0: Disable SlevomatCodingStandard.Classes.ClassConstantVisibility.MissingConstantVisibility.
- PHP 8.2+: Ensure DeclareStrictTypes rules align with your project’s strict_types=1 setting.
False Positives
- Laravel Facades: Exclude use Illuminate\Support\Facades\* from SlevomatCodingStandard.Namespaces.UseFromSameNamespace.
- Dynamic Properties: Disable PSR12.Classes.PropertyDeclaration if using PHP 8.2’s read-only properties.
Performance Issues
- Large Codebases: Use --cache to speed up repeated runs:
```
./vendor/bin/phpcs --cache=.phpcs.cache
```
- Exclude Heavy Directories: Add patterns like */tests/* to skip slow test files.
Auto-Fix Limitations
- phpcbf may not fix all issues (e.g., complex alignment rules). Manually review changes.
- Backup code before running phpcbf on critical files.

Debugging Tips

Verbose Output Run with --verbose to debug rule application:
```
./vendor/bin/phpcs --standard=Wdes --verbose
```

Rule-Specific Help Check which rules apply to a file:

./vendor/bin/phpcs --standard=Wdes --report=summary file.php

Isolate Violations Test a single file or directory:
```
./vendor/bin/phpcs app/Models/User.php
```

Pro Tips

Progressive Enforcement
- Start with --severity=5 (errors only) in CI, then lower to 3 (warnings) over time.
- Use phpcbf in local dev but block warnings in CI.

Custom Aliases Add to composer.json scripts for convenience:

"scripts": {
    "lint": "phpcs",
    "lint-fix": "phpcbf",
    "lint-ci": "phpcs --standard=Wdes --error-severity=3"
}

Document Exceptions Add a CODE_STYLE_EXCEPTIONS.md file to explain why certain rules are disabled:

## PHPCS Exceptions
- `Generic.Arrays.DisallowLongArraySyntax`: Legacy codebase uses PHP 5.3.
- `PSR12.Classes.PropertyDeclaration`: Dynamic properties in `app/Helpers.php`.

Monitor Adoption Track PHPCS violations over time using:
```
./vendor/bin/phpcs --standard=Wdes --report=summary --report-file=phpcs-report.txt
```
Compare reports weekly to measure improvement.

Extension Points

Add Custom Rules Extend the standard by including additional PHPCS rulesets:

<rule ref="Wdes"/>
<rule ref="SlevomatCodingStandard"/>
<rule ref="PSR12">
    <exclude name="PSR12.Namespaces.NoUnusedUses"/>
</rule>

Plugin Integration Use phpcs plugins like phpcs-security-audit for security checks:

composer require --dev phpcs-security-audit
./vendor/bin/phpcs --standard=Wdes --extensions=php,php5 --runtime-set testSecurityAudit true

Dynamic Rulesets Generate phpcs.xml dynamically based on PHP version (e.g., using a script):

// scripts/generate-phpcs-config.php
$phpVersion = phpversion();
$rules = ['Wdes'];
if ($phpVersion < '7.0') {
    $rules[] = 'Exclude[SlevomatCodingStandard.Classes.ClassConstantVisibility.MissingConstantVisibility]';
}
file_put_contents('phpcs.xml', generateXml($rules));

Coding Standard Laravel Package