Getting Started

Minimal Steps

Installation:
```
composer require --dev sabre/cs
```
Ensure phpcs is installed globally or via Composer (composer require --dev squizlabs/php_codesniffer).
First Use Case: Run a basic check on your Laravel project’s source files:
```
vendor/bin/phpcs --standard=sabre src/
```
For a more granular check (e.g., only warnings and errors):
```
vendor/bin/phpcs --standard=sabre --warning-severity=0 --error-severity=0 src/
```
Where to Look First:
- Ruleset Configuration: Check vendor/sabre/cs/Sabre.ruleset.xml for Sabre-specific rules.
- PHP_CodeSniffer Docs: Refer to PHP_CodeSniffer’s documentation for advanced usage.
- Laravel Integration: Use Laravel’s Artisan to wrap the check in a custom command (see Implementation Patterns).

Implementation Patterns

Usage Patterns

Laravel Artisan Command: Create a custom command to integrate sabre/cs into Laravel’s workflow:

php artisan make:command SabreCsCheck

Update the generated file (app/Console/Commands/SabreCsCheck.php):

<?php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Process\Process;
use Symfony\Component\Process\Exception\ProcessFailedException;

class SabreCsCheck extends Command
{
    protected $signature = 'cs:sabre {--path= : Path to check}';
    protected $description = 'Run Sabre coding standards check';

    public function handle()
    {
        $path = $this->option('path') ?: base_path('src');
        $process = new Process(['phpcs', '--standard=sabre', $path]);
        $process->run();

        if (!$process->isSuccessful()) {
            throw new ProcessFailedException($process);
        }

        $this->info('Sabre CS check passed!');
    }
}

Run the command:

php artisan cs:sabre --path=src/

Git Hook Integration: Add a pre-commit hook to enforce Sabre standards before commits:
```
# .git/hooks/pre-commit
#!/bin/sh
php artisan cs:sabre --path=src/ || exit 1
```
Ensure the hook is executable:
```
chmod +x .git/hooks/pre-commit
```

CI/CD Pipeline: Integrate sabre/cs into your CI pipeline (e.g., GitHub Actions):

name: Sabre CS Check
on: [push, pull_request]
jobs:
  sabre-cs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-php@v2
        with:
          php-version: '8.1'
      - run: composer install --dev
      - run: vendor/bin/phpcs --standard=sabre --warning-severity=0 src/

Custom Ruleset Extension: Extend Sabre’s ruleset by creating a custom phpcs.xml file in your project root:

<?xml version="1.0"?>
<ruleset name="App Sabre Rules">
    <arg name="standard" value="Sabre"/>
    <arg name="extensions" value="php"/>
    <arg name="tab-width" value="4"/>
    <file>src/</file>
    <!-- Override or add custom rules -->
    <rule ref="Sabre.Spaces.DisallowSpaceAfterCast">
        <severity>warning</severity>
    </rule>
</ruleset>

Reference this file in your CLI commands:

vendor/bin/phpcs -p phpcs.xml src/

Gotchas and Tips

Pitfalls

Archived Package:
- The package is no longer maintained. Be cautious of potential compatibility issues with newer PHP versions or PHP_CodeSniffer updates.
- Workaround: Fork the repository and maintain it internally if critical fixes are needed.
Rule Conflicts:
- Sabre’s rules may conflict with Laravel’s default PSR-12 standards (e.g., line endings, brace placement).
- Example Conflict: Sabre may enforce PSR1 (fully qualified namespaces), while Laravel defaults to PSR12 (relative namespaces).
- Solution: Use PHP_CodeSniffer’s --ignore flag or override rules in your custom phpcs.xml.
Performance Overhead:
- Running sabre/cs on large codebases (e.g., monorepos) can be slow, especially in CI.
- Tip: Use --parallel flag (if supported) or limit the scope of checks:
```
vendor/bin/phpcs --standard=sabre --parallel=4 src/
```
Blade File Handling:
- Sabre’s ruleset may not handle Laravel’s Blade templates (*.blade.php) optimally.
- Workaround: Exclude Blade files from checks or create a custom ruleset for them.
Dependency Bloat:
- Installing sabre/cs pulls in PHP_CodeSniffer and its dependencies, which may not be needed otherwise.
- Tip: Use Composer’s replace or conflict directives if you’re already using a different static analysis tool.

Debugging Tips

Verbose Output: Enable verbose mode to debug rule violations:
```
vendor/bin/phpcs --standard=sabre --verbose src/
```
Diff Mode: Use the --diff flag to see exactly what changes are needed to fix violations:
```
vendor/bin/phpcs --standard=sabre --diff src/
```
Rule-Specific Debugging: Isolate which rule is causing issues by running a specific rule:
```
vendor/bin/phpcs --standard=sabre --ruleset=Sabre.Spaces.DisallowSpaceAfterCast src/
```
Configuration Validation: Validate your phpcs.xml configuration for syntax errors:
```
vendor/bin/phpcs -i
```

Extension Points

Custom Rules: Extend Sabre’s ruleset by adding custom rules in your phpcs.xml:

<rule ref="Sabre">
    <exclude name="Sabre.Spaces.DisallowSpaceAfterCast"/>
    <include name="CustomRule"/>
</rule>

Integration with Laravel:
- Pint Integration: If using Laravel Pint, create a custom preset that aligns with Sabre’s standards.
- IDE Support: Configure PHPStorm or VSCode to use Sabre’s ruleset for real-time feedback:
  - PHPStorm: Go to Settings > Editor > Inspections > PHP > PHP_CodeSniffer and add the Sabre ruleset.
  - VSCode: Use the PHP_CodeSniffer extension and configure it to use the Sabre ruleset.
Automated Fixes: Use PHP_CodeSniffer’s --fix flag to automatically fix minor violations (if supported by the ruleset):
```
vendor/bin/phpcs --standard=sabre --fix src/
```

Documentation: Document Sabre’s coding standards in your project’s CONTRIBUTING.md or CODE_OF_CONDUCT.md to onboard new developers:

## Coding Standards
This project follows the [Sabre coding standards](https://github.com/sabre-io/cs).
Run `composer cs-check` to validate your code before submitting a PR.

Cs Laravel Package