Composer Plugin Laravel Package

Technical Evaluation

Architecture Fit

• Legacy System Integration: The plugin is exclusively designed for Contao 3.x modules, which are not Laravel-native. While Laravel can technically integrate Contao 3 modules via Composer, the plugin’s core functionality (symlinking to system/modules/) conflicts with Laravel’s PSR-4 autoloading and vendor-based dependency isolation. A Laravel project would need to:
  • Accept Contao’s filesystem structure (e.g., system/modules/) alongside Laravel’s conventions, risking namespace pollution or autoload conflicts.
  • Bypass Laravel’s OpCache for Contao modules, as Contao 3 relies on legacy class loading (e.g., TL_* classes).
• Hybrid Contao 3/4 Support: The plugin allows dual compatibility, but Contao 4’s Symfony bundles are incompatible with Laravel’s architecture. A Laravel project would not benefit from Contao 4 features (e.g., DIC) while using this plugin.
• Composer Plugin Model: The plugin hooks into Composer’s lifecycle, not Laravel’s. This means:
  • Root Project Dependency: The plugin must be installed in the root composer.json (not a Laravel package’s composer.json), limiting granularity.
  • No Laravel Service Provider: Unlike Laravel packages, this plugin does not register services or routes, requiring manual Contao integration (e.g., TL_Module hooks).

Technical Risk

Key Questions

1. Why Contao 3?

   • Is the project locked into Contao 3 (e.g., legacy client contracts, unsupported Contao 4 features)?
   • Are there no Contao 4 alternatives (e.g., Symfony bundles or Laravel-compatible modules)?

2. Laravel Integration Strategy

   • How will Contao modules coexist with Laravel’s autoloader? (e.g., custom composer.json autoload maps?)
   • Will Contao modules register routes/services in Laravel? If so, how? (e.g., via TL_Hooks or a Laravel service provider?)

3. Deployment Workflow

   • How will system/modules/ symlinks be managed in CI/CD? (e.g., Docker volumes, post-deploy scripts?)
   • Will the plugin’s runonce scripts conflict with Laravel’s migrations?

4. Future-Proofing

   • What’s the exit strategy if Contao 3 is deprecated? (e.g., rewrite modules as Laravel packages?)
   • Can the plugin be replaced with a Laravel-specific solution (e.g., a custom Composer plugin for vendor/contao-modules)?

Integration Approach

Stack Fit

• Laravel + Contao 3 Hybrid:

  • The plugin does not natively integrate with Laravel, but it can be forced into a hybrid stack by:
    • Installing the plugin in the root composer.json (not a Laravel package).
    • Configuring Contao to coexist with Laravel (e.g., shared vendor/, separate system/).
    • Using custom autoload rules to exclude Contao modules from Laravel’s PSR-4 loader.
  • Compatibility Issues:
    • Contao’s global namespace (TL_*) will pollute Laravel’s global namespace.
    • Contao’s database schema may conflict with Laravel’s migrations.
    • Contao’s routing (e.g., index.php?do=module) will not integrate with Laravel’s router.

• Alternative Approaches:

  Approach	Pros	Cons
  Use Plugin as-Is	Minimal changes; leverages Contao community support.	High risk of conflicts; no Laravel integration.
  Custom Laravel Composer Plugin	Full control over autoloading/routing.	High development effort; no Contao community support.
  Symfony Bundles (Contao 4)	Native Laravel/Symfony compatibility.	Requires rewriting Contao 3 modules; Contao 4 may not be viable.
  Static File Copy (No Plugin)	Avoids Composer plugin overhead.	Manual symlink management; no runonce support.

Migration Path

1. Assess Contao 3 Dependencies:

   • Audit all Contao 3 modules for namespace conflicts, database dependencies, and PHP version requirements.
   • Document blockers (e.g., modules using registerHook() or TL_Module directly).

2. Configure Root composer.json:

   {
     "require": {
       "contao/core-bundle": "~3.5",
       "contao-community-alliance/composer-plugin": "~2.4 || ~3.0"
     },
     "extra": {
       "contao": {
         "sources": {
           "vendor/contao-modules/module1": "system/modules/module1"
         }
       }
     },
     "autoload": {
       "psr-4": {
         "App\\": "app/",
         // Exclude Contao modules from Laravel's autoloader
       },
       "files": [
         "vendor/contao-modules/module1/config/autoload.php"
       ]
     }
   }
   

   • Use files autoload for Contao modules that need legacy class loading.

3. Isolate Contao Filesystem:

   • Place system/ outside Laravel’s vendor/ (e.g., public/contao/system/).
   • Configure Contao’s TL_ROOT to point to the shared directory.

4. Handle Routing:

   • Use Laravel’s rewrite middleware to proxy Contao requests to index.php.
   • Example:

     // routes/web.php
     Route::prefix('contao')->group(function () {
         Route::get('{path}', function ($path) {
             return app()->handle(
                 Request::create("/contao/index.php?do=$path")
             );
         });
     });
     

5. Database Integration:

   • Use Laravel’s Schema::connection() to manage Contao tables.
   • Example:

     Schema::connection('contao')->table('tl_content')->get();
     

Compatibility

Sequencing

1. Phase 1: Proof of Concept

   • Install the plugin in a new Laravel project.
   • Test basic Contao module installation (e.g., a hello world module).
   • Verify autoloading, routing, and database access.

2. Phase 2: Integration

   • Migrate one critical Contao module to the hybrid setup.
   • Resolve namespace conflicts and routing issues.

3. Phase 3: CI/CD Pipeline

   • Automate symlink creation in Docker/Kubernetes.
   • Test **Composer updates