Contao Build Tools Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Incompatibility: The package is exclusively designed for Contao, leveraging Symfony best practices (e.g., src/ directory, Contao-specific namespaces like Contao\). Laravel’s app/ structure and App\ namespace create fundamental conflicts:
  • Directory Structure: Contao assumes src/ for code; Laravel uses app/.
  • Namespace Rules: PHPStan/Rector presets target Contao’s Contao\ namespace, which may incorrectly flag Laravel’s App\ or Illuminate\ classes.
  • Tool Assumptions: Deployer integration is tailored for Contao’s module system (e.g., includeSystemModules()), irrelevant to Laravel’s composer-based autoloading.
• Opinionated Constraints: The package enforces Symfony/Contao conventions (e.g., no config in src/). Laravel’s config/, routes/, and database/ directories would require manual overrides or rejection.
• Partial Overlap: Underlying tools (PHPStan, ECS, Rector) are generic but Contao-specific configurations (e.g., phpstan.neon rules) are incompatible without heavy customization.

Integration Feasibility

• Low for Laravel: The package’s core value (Contao-specific tooling) is non-applicable. Key barriers:
  • Tool Misconfiguration: PHPStan’s default rules may false-positive Laravel patterns (e.g., facades, service containers).
  • Deployer Irrelevance: Laravel’s deployment ecosystem (Forge, Envoyer) differs from Contao’s Deployer workflows.
  • Composer Script Conflicts: Laravel’s composer.json scripts (e.g., artisan) may clash with Contao’s composer run commands.
• Feasible for Contao: If the product is Contao-based, integration is straightforward but opinionated. Teams must adhere to:
  • src/ directory for code.
  • Symfony-style bundles.
  • Contao’s namespace conventions.

Technical Risk

Key Questions

1. Is the product Contao-based?
   • If no, discard this package and adopt Laravel-native tools.
   • If yes, evaluate whether the team can adopt Contao/Symfony conventions.
2. Can we tolerate the src/ directory constraint?
   • Laravel teams typically cannot without significant refactoring.
3. Do we need Contao-specific CQ/CS rules?
   • If no, use generic tools (e.g., phpstan/phpstan + Laravel extensions).
4. Is Deployer a priority for Laravel deployments?
   • If yes, use Laravel Forge/Envoyer instead.
5. What’s the cost of customizing Contao configs for Laravel?
   • High; likely not worth the effort compared to alternatives.

Integration Approach

Stack Fit

• Laravel: Poor Fit
  • Tools: PHPStan, ECS, Rector, and Stylelint are generic but the presets/configs are Contao-specific.
  • Deployer: Irrelevant to Laravel’s deployment workflows.
  • Composer Scripts: Laravel’s post-autoload-dump or post-update-cmd may conflict with Contao’s composer run commands.
• Contao: Good Fit (with Caveats)
  • Aligns with Symfony best practices (e.g., src/ directory).
  • Provides batteries-included Contao-specific tooling.
  • Opinionated: Requires buy-in to Contao/Symfony conventions.

Migration Path

Compatibility

• Composer Dependencies:
  • Safe for Laravel: Core tools (PHPStan, ECS) can coexist if Contao-specific configs are removed.
  • Risky Dependencies: deployer/deployer is optional but not Laravel-compatible.
• PHP Version: Compatible with Laravel’s PHP 8.0+ (package supports PHP 7.4+).
• Contao-Specific Assumptions:
  • Breaking for Laravel:
    • src/ directory assumption.
    • Contao namespace rules (e.g., Contao\ vs. App\).
    • Rector presets for Contao upgrades (e.g., Contao\BackendTemplate).
  • Workaround: Create custom configs that exclude Contao-specific logic.

Sequencing

1. For Laravel Projects:
   • Step 1: Uninstall the package.
   • Step 2: Install Laravel-compatible alternatives:

     composer require --dev phpstan/phpstan phpstan/extension-installer phpstan/laravel
     composer require --dev friendsofphp/php-cs-fixer laravel-pint
     

   • Step 3: Configure PHPStan for Laravel:

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

   • Step 4: Replace Contao’s GitHub Action with a Laravel-compatible workflow (e.g., using phpstan and pint).
2. For Contao Projects:
   • Step 1: Install the package:

     composer require --dev terminal42/contao-build-tools
     

   • Step 2: Customize configs in the project root (ecs.php, phpstan.neon).
   • Step 3: Test the build-tools script and GitHub Action.
   • Step 4: Integrate Deployer if needed (requires deployer/deployer).

Operational Impact

Maintenance

• Laravel Projects:
  • High Overhead:
    • Customization Required: Remove Contao-specific rules/configs.
    • Risk of Drift: Manual overrides may break on package updates.
  • Better Alternatives:
    • Laravel’s ecosystem (e.g., laravel-pint, phpstan/laravel) is actively maintained and optimized for Laravel.
  • Long-Term Cost: Not sustainable; better to adopt standalone tools.
• Contao Projects:
  • Low Overhead (If Aligned):
    • Reduces boilerplate for CQ/CS tooling.
    • Contao-specific presets lower maintenance for teams using Contao.
  • Caveats:
    • Lock-in to Contao/Symfony conventions (e.g., src/ directory).
    • Updates may require config adjustments (e.g., new PHP