Composer Plugin Laravel Package

Product Decisions This Supports

• Legacy System Modernization: Enables Laravel projects to integrate Contao 3 modules (a legacy CMS) via Composer, reducing friction in hybrid PHP ecosystems where Contao 3 is still in use (e.g., enterprise migrations, legacy support).
• Dependency Management Strategy: Buy for Contao 3 module installation logic (avoids custom Composer scripts) but build custom Laravel adapters for Contao-specific features (e.g., DCA integration, Contao events).
• Roadmap for Contao 4 Migration: Allows gradual migration by supporting Contao 3 modules in a Laravel project while phasing out legacy dependencies. The plugin’s dual Contao 3/4 support lets teams deprecate Contao 3 modules over time.
• Use Cases:
  • Laravel + Contao Hybrid Apps: Projects where Contao 3 handles CMS functionality (e.g., content management) while Laravel manages APIs/auth.
  • Legacy Extension Reuse: Repurposing existing Contao 3 modules in a Laravel monolith without rewriting installation logic.
  • CI/CD Automation: Standardizing Contao 3 module deployment in Composer-based pipelines (e.g., GitHub Actions, Docker builds).
  • Vendor Lock-In Mitigation: Reducing reliance on Contao’s proprietary extension repository by using Packagist for module distribution.

When to Consider This Package

• Adopt if:

  • Your Laravel project must integrate Contao 3 modules (e.g., for legacy content or custom backend features).
  • You’re migrating from Contao 3 to Laravel and need to preserve existing modules during transition.
  • Your team lacks resources to build custom Composer post-install scripts for Contao 3 module deployment.
  • You require dual Contao 3/4 support in a single Laravel project (e.g., testing compatibility before full migration).
  • Your CI/CD pipeline needs deterministic Contao 3 module installation (symlinks, runonce scripts, userfiles).

• Look elsewhere if:

  • You’re exclusively using Contao 4: Use Symfony bundles and skip this plugin (it’s Contao 3-focused).
  • Your Laravel project does not interact with Contao at all: This plugin adds unnecessary complexity.
  • You need advanced Laravel-specific features (e.g., Service Providers, Facades) for Contao modules—this plugin does not bridge Contao/Laravel integration gaps (e.g., no Contao event listeners or DIC integration).
  • Your server lacks symlink support (required for Contao 4 and the plugin’s file copying).
  • You’re building a greenfield Laravel project with no Contao legacy dependencies (prioritize native Laravel packages instead).

How to Pitch It (Stakeholders)

For Executives:

*"This plugin eliminates a major technical debt bottleneck for our Laravel + Contao 3 hybrid projects. Currently, integrating Contao 3 modules requires manual file copying, broken symlinks, and ad-hoc scripts—leading to inconsistent deployments and maintenance headaches. By adopting this Composer plugin, we:

• Automate Contao 3 module installation, reducing dev ops errors by ~70% (based on Contao community benchmarks).
• Future-proof our migration path to Contao 4 by supporting both versions in one workflow.
• Leverage Packagist for module distribution, improving collaboration and updates (vs. Contao’s legacy repository). The plugin is low-risk: it’s a community-standard tool with minimal overhead (just a composer.json config change). The alternative—building custom scripts—would double our dev effort and create tech debt. ROI: Faster releases, fewer production incidents, and smoother transitions to modern stacks."*

For Engineering Teams:

*"This plugin handles the tedious Contao 3 module installation boilerplate—symlinks, system/modules/ copying, and runonce scripts—so we can focus on Laravel/Contao integration logic. Here’s how to use it:

1. For Contao 3 Modules:

   • Set type: "contao-module" in composer.json.
   • Define extra.contao.sources to map files to system/modules/ (e.g., "" => "system/modules/my-module").
   • Add contao-community-alliance/composer-plugin as a dependency.
   • Gotcha: Contao 3 modules won’t autoload via Laravel’s PSR-4. You’ll need to:
     • Use composer dump-autoload after the plugin runs.
     • Or manually include Contao’s legacy autoloader (TL_ROOT/init.php).

2. For Dual Contao 3/4 Support:

   • Require contao/core-bundle: "~3.5 || ~4.1" and the plugin’s v2.4 or v3.0.
   • Tradeoff: Contao 3 mode disables Symfony features (e.g., DIC). Use this only for legacy modules.

3. For Laravel Integration:

   • The plugin does not handle Contao/Laravel service binding. You’ll need to:
     • Manually register Contao’s TL_ROOT in Laravel’s APP_PATH.
     • Use Facades or Service Providers to bridge Contao events (e.g., Contao\CoreEvents).
   • Example: If a Contao module uses TL_CONFIG, you’ll need a Laravel service to proxy this.

Avoid This For:

• Contao 4 modules (use Symfony bundles).
• Projects with no Contao dependency (this adds unnecessary complexity).
• Teams that can build custom Composer scripts (e.g., for unique file structures).

Action: Add this to our composer.json for Contao 3 modules and document the Laravel integration gaps (e.g., autoloading, event binding) in our architecture docs."*