Getting Started

Minimal Steps

Install the Package

composer require phpcq/repository-definition --dev

Add to composer.json under require-dev if using in CI/CD:

"require-dev": {
    "phpcq/repository-definition": "^1.0"
}

Create a Repository Definition File Add a .phpcq.yml (or .phpcq.json) in your Laravel project root:

repositories:
  - path: .
    tools:
      - name: phpcs
        config: "vendor/bin/phpcs"
        ruleset: "vendor/squizlabs/php_codesniffer/CodeSniffer/CodeSniffer.xml"
        standard: "PSR12"
      - name: phpmd
        config: "vendor/bin/phpmd"
        rulesets: ["codesize", "unusedcode"]
        exclude: ["tests/", "vendor/"]

Run PHPCQ Locally Use a custom script in composer.json:

"scripts": {
    "phpcq": "vendor/bin/phpcq check"
}

Execute with:

composer phpcq

Integrate with CI (GitHub Actions Example) Add to .github/workflows/phpcq.yml:

jobs:
  phpcq:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-php@v3
        with:
          php-version: '8.2'
      - run: composer install --dev
      - run: composer phpcq

Implementation Patterns

Workflows

Standardized CI Checks

Use PHPCQ as a pre-commit or pre-merge gate in CI/CD.

Example GitHub Actions workflow:

- name: Run PHPCQ
  run: |
    composer phpcq
    if [ $? -ne 0 ]; then
      echo "PHPCQ failed. Check the report for details."
      exit 1
    fi

Laravel-Specific Extensions

Extend the schema for Laravel concerns (e.g., Blade templates, Eloquent queries):

repositories:
  - path: .
    tools:
      - name: phpcs
        custom_rules:
          - "App/Rules/BladeSniffs.php"

Create a custom PHPCQ rule for Laravel:

// app/Rules/CustomPhpcsRuleset.php
return [
    '@PSR12',
    'App/Rules/BladeSniffs',
    'App/Rules/EloquentSniffs',
];

Dynamic Configuration

Load PHPCQ configs from Laravel’s environment or database:

// config/phpcq.php
return [
    'tools' => [
        'phpcs' => [
            'ruleset' => env('PHPCQ_RULESET', 'PSR12'),
        ],
    ],
];

Use Laravel’s Service Container to resolve PHPCQ configs:

$this->app->singleton('phpcq.config', function () {
    return require config_path('phpcq.php');
});

Parallel Execution

Split PHPCQ checks across CI jobs for large codebases:

jobs:
  phpcq-core:
    run: composer phpcq -- --path=app/Http
  phpcq-tests:
    run: composer phpcq -- --path=tests

Integration Tips

Combine with Laravel Tools Use PHPCQ alongside pint, phpstan, or psalm:

# .phpcq.yml
repositories:
  - path: .
    tools:
      - name: phpcs
      - name: phpmd
      - name: phpstan
        config: "vendor/bin/phpstan analyse --level=5"

Custom Artisan Command Create a Laravel-specific PHPCQ command:

// app/Console/Commands/PhpcqCheck.php
namespace App\Console\Commands;

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

class PhpcqCheck extends Command
{
    protected $signature = 'phpcq:check';
    protected $description = 'Run PHPCQ checks with Laravel-specific configs';

    public function handle()
    {
        $process = new Process(['composer', 'phpcq']);
        $process->run();

        if (!$process->isSuccessful()) {
            $this->error($process->getOutput());
            exit(1);
        }

        $this->info('PHPCQ checks passed!');
    }
}

Reporting to Laravel Parse PHPCQ output and store results in a Laravel model:

// app/Services/PhpcqReporter.php
public function report()
{
    $output = shell_exec('composer phpcq --format=json');
    $data = json_decode($output, true);

    foreach ($data['violations'] as $violation) {
        PhpcqViolation::create([
            'file' => $violation['file'],
            'line' => $violation['line'],
            'message' => $violation['message'],
            'severity' => $violation['severity'],
        ]);
    }
}

Gotchas and Tips

Pitfalls

Schema Validation Failures
- Issue: PHPCQ may fail silently if the YAML/JSON schema is invalid.
- Fix: Validate your config file using:
```
composer phpcq validate
```
- Tip: Use a schema validator like spatie/fork to pre-check configs:
```
use Spatie\Fork\YamlFrontMatterParser;

$config = YamlFrontMatterParser::parse(file_get_contents('.phpcq.yml'));
```
Tooling Conflicts
- Issue: Running PHPCQ alongside pint, phpstan, or psalm may cause redundant checks or conflicts.
- Fix: Define clear ownership in your composer.json:
```
"scripts": {
    "lint": "phpstan && phpcq && pint --test",
    "ci": "phpstan && phpcq"
}
```
- Tip: Use PHPCQ for static analysis and Laravel tools for formatting or runtime analysis.

Performance in CI

Issue: PHPCQ can slow down CI pipelines if not optimized.

Fix:

Cache dependencies:

- uses: actions/cache@v3
  with:
    path: vendor
    key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}

Run checks in parallel (see Implementation Patterns).

Exclude unnecessary paths:

repositories:
  - path: .
    tools:
      - name: phpcs
        exclude: ["storage/", "bootstrap/cache/"]

Laravel-Specific Blind Spots
- Issue: PHPCQ may not cover Laravel-specific concerns (e.g., Blade syntax, Facade usage).
- Fix: Extend the schema with custom rules:
```
repositories:
  - path: .
    tools:
      - name: phpcs
        custom_rules:
          - "App/Rules/LaravelBladeSniffs.php"
```
- Tip: Create a shared Laravel PHPCQ ruleset in a package (e.g., laravel-phpcq-rules).
Unmaintained Package Risk
- Issue: The package has 0 stars/dependents and may lack updates.
- Fix:
  - Fork and maintain the package if critical.
  - Monitor the PHPCQ GitHub for updates.
  - Use a wrapper package to abstract dependencies.

Debugging

Verbose Output Enable debug mode in .phpcq.yml:
```
debug: true
```
Or via CLI:
```
composer phpcq -- --verbose
```
Dry Runs Test PHPCQ without failing the build:
```
composer phpcq -- --dry-run
```
Isolated Checks Run PHPCQ on a single file or directory:
```
composer phpcq -- --path=app/Http/Controllers
```

Extension Points

Custom Tool Integrations Extend PHPCQ to support additional tools (e.g., psalm, security-checker):
```
repositories:
  - path: .
    tools:
      - name: psalm
        config: "vendor/bin/psalm --init"
```
- Tip: Submit a PR to the PHPCQ core team to add native support.
Dynamic Rule Loading Load PHPC

Repository Definition Laravel Package