Getting Started

Minimal Steps for Laravel Developers

Skip Installation (unless working on a Contao project):
- This package is not designed for Laravel and will introduce conflicts with Laravel’s directory structure (app/ vs. src/) and namespace conventions (App\ vs. Contao\).
- Exception: If you’re maintaining a hybrid Contao/Laravel project, isolate Contao-specific tools in a separate Composer script.
For Contao Projects (Non-Laravel):
- Install via Composer:
```
composer require --dev terminal42/contao-build-tools
```
- Run a basic code style check:
```
composer run cs-fixer
```
- Verify PHPStan analysis:
```
composer run phpstan
```
- Use the GitHub Action template in .github/workflows/ci.yml (customize for Contao-specific paths).
First Use Case:
- Contao: Automate code quality checks in CI/CD (e.g., block merges with PHPStan errors).
- Laravel: Replace with Laravel-compatible tools (e.g., phpstan/laravel, laravel-pint).

Implementation Patterns

Usage Patterns for Contao Projects

Code Quality Workflow:

Pre-commit Hooks: Integrate cs-fixer and phpstan via tools like Husky or Git hooks.

composer run cs-fixer --dry-run  # Check without fixing
composer run phpstan --level=5   # Strict analysis

CI Pipeline: Use the provided GitHub Action or adapt it for Contao:

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

Rector for Upgrades:

Use Rector to migrate Contao-specific code (e.g., legacy Contao\Backend to new APIs):

composer run rector --dry-run  # Preview changes
composer run rector            # Apply upgrades

Customize rector.php to target Contao bundles:

return static::configure()
    ->withPaths([__DIR__.'/src'])
    ->withRule(ContaoUpgrade::class);

Deployer Integration:

Configure deploy.php for Contao deployments (e.g., syncing assets/ and system/):

(new Deployer('example.com', 'user', '/usr/bin/php'))
    ->addTarget('prod', '/var/www/contao', 'https://example.com')
    ->includeSystemModules()
    ->addUploadPaths([
        'assets/',
        'files/',
    ])
    ->run();

Laravel Note: Ignore Deployer; use Laravel Forge, Envoyer, or custom scripts.

Customization:

Override default configs in the project root:

PHP-CS-Fixer: ecs.php

return static::setPath(__DIR__.'/vendor/drupal/coder/coder_sniffer/Contao')
    ->setRules([
        '@Contao' => true,
        'array_syntax' => ['syntax' => 'short'],
    ]);

PHPStan: phpstan.neon

includes:
    - vendor/terminal42/contao-build-tools/phpstan.neon
level: max

Laravel Integration Tips

Avoid Direct Use: The package’s src/ assumption conflicts with Laravel’s app/. Instead:

Use standalone tools:

composer require --dev phpstan/phpstan laravel-pint

Configure PHPStan for Laravel:

# phpstan.neon
includes:
    - vendor/phpstan/extension-installer/phpstan.neon
    - vendor/phpstan/phpstan-laravel/phpstan.neon

For CS fixing, use laravel-pint:

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

Gotchas and Tips

Pitfalls for Laravel Developers

Directory Structure Conflicts:
- Error: src/ directory not found (Laravel uses app/).
  - Fix: Do not install the package for Laravel projects. Use:
```
composer require --dev friendsofphp/php-cs-fixer
```
    Then configure .php-cs-fixer.dist.php manually.
Namespace Collisions:
- Error: PHPStan flags App\ namespace as invalid (expects Contao\).
  - Fix: Exclude Laravel namespaces in phpstan.neon:
```
excludeFiles:
    - app/Providers/*
    - app/Http/*
```
Deployer Irrelevance:
- Error: Deployer scripts fail due to Contao-specific assumptions (e.g., system/modules/).
  - Fix: Use Laravel’s deployment tools (Envoyer, Forge) or a custom Deployer config:
```
// deploy.php (Laravel-specific)
task('deploy', [
    'shared' => ['app/storage'],
    'writable' => ['app/storage', 'bootstrap/cache'],
]);
```
Rector Misconfigurations:
- Error: Rector applies Contao-specific rules to Laravel code (e.g., Route::resource()).
  - Fix: Skip Rector entirely for Laravel or create a custom rule set:
```
// rector.php (Laravel-only)
return static::configure()
    ->withPaths([__DIR__.'/app'])
    ->withRule(\Rector\Set\LaravelSetList::PHP_80);
```

GitHub Action Overrides:

Error: CI fails due to Contao-specific paths (e.g., src/).

Fix: Replace the GitHub Action with a Laravel-compatible workflow:

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

Debugging Tips

PHPStan Errors:
- Debug: Run PHPStan with --debug to identify misconfigured rules:
```
composer run phpstan --debug
```
- Contao Workaround: Extend phpstan.neon to ignore Contao-specific false positives:
```
arguments:
    paths:
        - src/
        - vendor/terminal42/contao-build-tools
```
CS Fixer Conflicts:
- Debug: Compare default rules (vendor/terminal42/contao-build-tools/ecs.php) with your ecs.php:
```
diff vendor/terminal42/contao-build-tools/ecs.php ecs.php
```
- Laravel Fix: Use laravel-pint instead:
```
composer require --dev laravel/pint
vendor/bin/pint --preset=laravel
```
Deployer Issues:
- Debug: Check Deployer’s --verbose output:
```
php deploy.php deploy --verbose
```
- Laravel Alternative: Use Laravel’s artisan deploy or Envoyer.

Extension Points

Custom PHPStan Rules:

Add Contao-specific rules to phpstan.neon:

includes:
    - vendor/terminal42/contao-build-tools/phpstan.neon
services:
    Contao\PageModel:
        methods:
            findById:
                returnType: Contao\PageModel|null

Rector Custom Rules:

Create a Contao-specific Rector rule:

// src/Rector/ContaoUpgradeRector.php
final class ContaoUpgradeRector extends AbstractRector
{
    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('Fixes Contao legacy code.', []);
    }

    public function refactor(ContaoLegacyNode $node): ?Node
    {
        // Custom logic
    }
}

Stylelint Extensions:

Add Contao-specific CSS rules to .stylelintrc:

{
    "extends": "stylelint-config-standard",
    "rules": {
        "selector-class-pattern": ["^([a-z][a-z0-

Contao Build Tools Laravel Package