Getting Started

Minimal Steps

Install the Package Require the package in your Laravel project via Composer:
```
composer require --dev sandfox.dev/code-standard
```
Ensure it’s listed under require-dev in composer.json.

Configure PHP_CodeSniffer Create or update .phpcs.xml in your project root:

<?xml version="1.0"?>
<ruleset name="Project Standard">
    <config name="installed_paths" value="./vendor/sandfox.dev/code-standard"/>
    <rule ref="SandfoxDev/CodeStandard"/>
</ruleset>

First Execution Run the linter on your Laravel codebase:
```
./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard app/
```
For Blade templates, add the --extensions=blade flag.

Quick CI Integration Add a GitHub Actions step (.github/workflows/phpcs.yml):

- name: PHP_CodeSniffer
  run: ./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --warning-severity=3 app/

Implementation Patterns

Daily Developer Workflow

Pre-Commit Hook Use husky to auto-run checks before commits:

npm install husky --save-dev
npx husky add .husky/pre-commit "phpcs --standard=SandfoxDev/CodeStandard --report=json app/ | jq -e '.files | length == 0'"

IDE Integration
- PHPStorm: Go to Settings > Editor > Inspections > PHP > Code Sniffer and set the standard to SandfoxDev/CodeStandard.
- VSCode: Install the "PHP Intelephense" extension and add to settings.json:
```
"intelephense.codeSnifferStandard": "SandfoxDev/CodeStandard"
```
Laravel-Specific Patterns
- Route Files: Exclude routes/ from strict checks if the standard doesn’t support Blade syntax:
```
<file>app/</file>
<exclude-pattern>routes/</exclude-pattern>
```
- Migrations: Add a custom rule to enforce snake_case for migration files:
```
<rule ref="SandfoxDev/CodeStandard.NamingConventions">
    <arg name="case" value="snake_case"/>
</rule>
```

Fixing Violations Use php-cs-fixer to auto-fix common issues:

composer require --dev friendsofphp/php-cs-fixer
./vendor/bin/php-cs-fixer fix --rules=@SandfoxDev/CodeStandard --dry-run

Gotchas and Tips

Common Pitfalls

Blade Template Support
- The standard may not natively support Blade syntax. Workaround: Exclude Blade files or use a custom rule:
```
<exclude-pattern>*.blade.php</exclude-pattern>
```
Laravel Facade Conflicts
- Rules like NoUnusedImports may flag Laravel facades (e.g., use Illuminate\Support\Facades\Log;). Fix:
```
<rule ref="Generic.Files.UnusedUses">
    <exclude name="Illuminate\Support\Facades.*"/>
</rule>
```
Performance in Large Codebases
- Running phpcs on app/ can be slow. Tip: Parallelize with --parallel or cache results:
```
./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --parallel=4 app/
```
Rule Overrides
- Overriding rules in .phpcs.xml may break updates. Best Practice: Document overrides and pin the package version:
```
"sandfox.dev/code-standard": "1.0.0"  // Pin to a stable version
```

Debugging Tips

Verbose Output: Use --verbose to debug rule application:

./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --verbose app/

Rule-Specific Checks: Test individual rules:

./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --rules=SandfoxDev/CodeStandard.NamingConventions app/

Custom Reports: Generate HTML reports for team reviews:

./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --report=html > phpcs-report.html

Extension Points

Custom Rules Extend the standard by creating a child ruleset:

<ruleset>
    <rule ref="SandfoxDev/CodeStandard"/>
    <rule ref="Custom.Namespace">
        <properties>
            <property name="prefix" value="App\Rules"/>
        </properties>
    </rule>
</ruleset>

Laravel-Specific Additions Add Laravel-aware rules (e.g., for Route::prefix usage):

<rule ref="Custom.Laravel.RoutePrefix">
    <properties>
        <property name="allowedPrefixes" value="admin,api"/>
    </properties>
</rule>

CI-Specific Configurations Use environment variables to toggle strictness in CI:

- name: PHP_CodeSniffer (Strict)
  if: github.ref == 'refs/heads/main'
  run: ./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --warning-severity=5 app/

Code Standard Laravel Package