## Getting Started

### Minimal Setup
1. **Install the package** in your Laravel project:
   ```bash
   composer require --dev contributte/qa

Create a custom ruleset file (e.g., phpcs.xml) in your project root:

<?xml version="1.0"?>
<ruleset name="Project Standards">
    <rule ref="./vendor/contributte/qa/ruleset.xml"/>
    <!-- Optionally override specific rules -->
    <rule ref="rules/Squiz.WhiteSpace.DisallowTabCharacter">
        <severity>warning</severity>
    </rule>
</ruleset>

Run PHP_CodeSniffer against your codebase:

vendor/bin/phpcs --standard=phpcs.xml app/

Auto-fix violations (where applicable):

vendor/bin/phpcbf --standard=phpcs.xml app/

First Use Case: CI/CD Integration

Add a GitHub Actions workflow (.github/workflows/qa.yml) to enforce standards on every push:

name: QA Checks
on: [push, pull_request]

jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install
      - run: vendor/bin/phpcs --standard=phpcs.xml --report=checkstyle | tee results.xml
      - uses: jwgmeligmeyling/checkstyle-github-action@v1
        with:
          path: results.xml

Implementation Patterns

Workflow: Daily Development

Local Checks:

Run phpcs on-demand during development:

alias phpcs="vendor/bin/phpcs --standard=phpcs.xml --colors"

Use phpcbf for quick fixes:

vendor/bin/phpcbf --standard=phpcs.xml --diff app/

IDE Integration:
- Configure PHPStorm to use phpcs.xml as the Code Sniffer profile:
  - Settings > Languages & Frameworks > PHP > Code Sniffer
  - Set Configuration file to phpcs.xml
  - Enable Run inspection on save

Team Onboarding:

Include a CONTRIBUTING.md snippet:

## Code Standards
This project enforces [Contributte QA](https://github.com/contributte/qa) standards.
Run `composer cs-check` to validate your changes before submitting a PR.

Laravel-Specific Patterns

Service Provider Integration: Create a QACheckServiceProvider to register commands:

// app/Providers/QACheckServiceProvider.php
public function register()
{
    $this->commands([
        Commands\QACheckCommand::class,
    ]);
}

Command implementation:

// app/Console/Commands/QACheckCommand.php
public function handle()
{
    $exitCode = Artisan::call('phpcs', [
        '--standard=phpcs.xml',
        '--report=full',
        '--colors',
        app_path('..'),
    ]);
    if ($exitCode !== 0) {
        $this->error('Code standards violations found!');
        exit(1);
    }
}

Custom Rules for Laravel Idioms: Extend the ruleset to handle Laravel-specific patterns:

<!-- phpcs.xml -->
<rule ref="./vendor/contributte/qa/ruleset.xml"/>
<rule ref="Custom/Laravel/DisallowFacadeDirectCalls">
    <severity>warning</severity>
</rule>

Create a custom sniff (e.g., app/Rules/Custom/Laravel/DisallowFacadeDirectCallsSniff.php):

class DisallowFacadeDirectCallsSniff implements Sniff
{
    public function register()
    {
        return [
            T_STRING => $this,
        ];
    }

    public function process(Tokens $tokens, $position)
    {
        $content = $tokens[$position][1];
        if (in_array($content, ['Auth', 'Cache', 'Route'])) {
            return new FixableError(
                'Direct facade calls are discouraged. Use dependency injection instead.',
                $position,
                $position + 1
            );
        }
        return null;
    }
}

Partial Integration: Use the package selectively for specific directories:
```
vendor/bin/phpcs --standard=phpcs.xml --ignore=tests,config app/
```

Gotchas and Tips

Pitfalls

PHP Version Mismatch:
- The package requires PHP 8.2+. Running on older versions will fail with:
```
Your PHP version (8.1) does not meet the minimum requirement (8.2).
```
- Fix: Update your PHP version or use a forked version (e.g., contributte/qa:0.3.x).
Deprecated Rules:
- Squiz.WhiteSpace.LanguageConstructSpacing is deprecated since PHP_CodeSniffer v3.3.0.
- Fix: Update your ruleset to use the new equivalent or suppress the deprecation warning:
```
<rule ref="Squiz.WhiteSpace.LanguageConstructSpacing">
    <severity>warning</severity>
    <properties>
        <property name="deprecated" value="true"/>
    </properties>
</rule>
```
Strict Typing Enforcement:
- The ruleset enforces declare(strict_types=1) at the top of files.
- Fix: Add this directive to all PHP files or configure the rule to allow exceptions:
```
<rule ref="SlevomatCodingStandard.TypeHints.Declaration">
    <properties>
        <property name="strict_types_declaration" value="false"/>
    </properties>
</rule>
```
CI Pipeline Failures:
- False positives in CI can clutter logs. Use --report=checkstyle for better integration:
```
vendor/bin/phpcs --standard=phpcs.xml --report=checkstyle | tee results.xml
```
- Tip: Combine with cs2pr for GitHub PR previews:
```
vendor/bin/phpcs --standard=phpcs.xml | cs2pr
```
Performance with Large Codebases:
- Running phpcs on large projects (e.g., 10K+ files) can be slow.
- Fix: Parallelize checks using parallel:
```
vendor/bin/phpcs --standard=phpcs.xml --parallel=4 app/
```

Debugging Tips

Isolate Rule Violations:

Test individual rules to identify the source of failures:

vendor/bin/phpcs --standard=SlevomatCodingStandard rules/TypeHints/Declaration.php

Inspect Ruleset:
- List all enabled rules to debug configurations:
```
vendor/bin/phpcs --standard=phpcs.xml --list-rules
```
Snapshot Testing:
- If using the package’s test suite, regenerate snapshots when modifying rules:
```
php bin/snapshots --sniffs
```

Extension Points

Custom Rulesets:

Create version-specific rulesets by extending the base:

<!-- ruleset-8.5.xml -->
<ruleset>
    <config name="php_version" value="8.5"/>
    <rule ref="./ruleset.xml"/>
    <rule ref="Custom/RulesForPHP85"/>
</ruleset>

Dynamic Rule Configuration:

Use PHP to generate rulesets dynamically (e.g., based on environment):

// Generate ruleset.php
$ruleset = new \PHP_CodeSniffer\Config();
$ruleset->addRule('SlevomatCodingStandard.TypeHints.Declaration');
$ruleset->save('phpcs.xml');

Integrate with Laravel Events:

Trigger QA checks on eloquent.saved or job.processed:

Event::listen('eloquent.saved', function ($model) {
    $exitCode = Artisan::call('phpcs', [
        '--standard=phpcs.xml',
        '--ignore=*/migrations/*',
        $model->getTable(),
    ]);
    if ($exitCode !== 0) {
        Log::error("Code standards violated in {$model->getTable()}");
    }
});

Pro Tips

Exclude Files:
- Use .phpcsignore to exclude files/directories:
```
# .phpcsignore
vendor/
node_modules/
storage/logs/*.log
```

Custom Error Messages:

Override default error messages for clarity:

<rule ref="Squiz.WhiteSpace.SpaceAfterCast">
    <properties>
        <property name="message" value="Missing space after

Qa Laravel Package