Installer Laravel Package

Product Decisions This Supports

• Modular Laravel Plugin Architecture: Enables a Contao-inspired component system for Laravel, allowing teams to develop reusable modules (e.g., admin dashboards, frontend widgets) as standalone Composer packages installed in a custom directory (e.g., plugins/). This aligns with Laravel’s ecosystem (e.g., Livewire, Nova) but with stricter isolation.
• Hybrid Contao/Laravel Projects: Justifies a build vs. buy decision for projects migrating from Contao to Laravel or requiring Contao-specific features (e.g., legacy integrations, DCA-based admin panels) without rewriting everything. Example: A Contao-powered frontend with a Laravel backend API.
• Polyrepo Workflow for Laravel: Supports a GitOps-friendly approach where Laravel components (e.g., auth-system, payment-gateway) are versioned independently in private Packagist repos, reducing monorepo bloat and enabling parallel development.
• Composer-Driven Customization: Replaces manual vendor/ symlinks or require hacks with a standardized installation process, improving reproducibility (e.g., composer require vendor/plugin:1.0).
• Legacy System Integration: Mitigates technical debt for teams incrementally modernizing Contao sites by gradually replacing Contao plugins with Laravel components while keeping the frontend intact.
• Open-Source Contributions: Facilitates LGPL-3.0-compliant Laravel packages (e.g., Contao-compatible form builders) that can be shared with the community under permissive licenses.

When to Consider This Package

• Avoid if:
  • Your project is pure Laravel with no Contao dependencies (use composer/installers or Laravel Packages instead).
  • You need tight coupling between components and Laravel’s core (e.g., Eloquent models, Blade templates). This package enforces physical separation, which may require extra glue code.
  • Your team lacks Composer customization experience (e.g., configuring autoload for non-standard paths).
  • Components require Laravel-specific dependencies (e.g., laravel/framework, illuminate/) that conflict with Contao’s LGPL-3.0 license.
  • You’re targeting PHP 8.2+ features (Contao’s installer may not support newer PHP versions).
• Consider alternatives:
  • For Laravel plugins: Use composer require vendor/package with PSR-4 autoloading (no custom installer needed).
  • For monolithic Laravel apps: Leverage Service Providers, Facades, or Laravel Packages for modularity.
  • For Contao migration: Evaluate Contao’s official Laravel bridge (if available) or rewrite components as Laravel Packages.
  • For custom directory structures: Use composer/installers with a custom plugin or symlinks in composer.json.

How to Pitch It (Stakeholders)

For Executives/Business Leaders

*"This package lets us modernize our Contao-based products without a full rewrite by treating Contao plugins as ‘Laravel-compatible’ components. Imagine taking a legacy Contao site—with its custom admin panels, widgets, or integrations—and gradually replacing them with Laravel-powered modules, all managed via Composer. For example:

• Faster iterations: Develop a new payment gateway as a Contao component today, then migrate it to Laravel tomorrow—without disrupting the live site.
• Cost savings: Avoid vendor lock-in by building proprietary features (e.g., analytics dashboards) as reusable components, then open-source them under LGPL-3.0 if needed.
• Future-proofing: If we ever phase out Contao, these components can seamlessly integrate into a pure Laravel stack.

Why now?

• Our Contao plugins are technical debt—this package turns them into strategic assets.
• Competitors using monolithic Contao plugins will struggle to adopt Laravel; we’ll out-innovate them with modular, composable features.
• ROI: 30% faster development cycles for custom features (based on Contao’s component isolation benefits).

Risk: Requires a small upfront investment to standardize our Composer/Laravel workflow. But the payoff is long-term flexibility."*

For Engineering/Technical Leads

*"This installer solves a specific pain point: How do we mix Contao components with Laravel without breaking autoloading or dependencies? Here’s the playbook:

Why Use It?

1. Contao Component Isolation:
   • Install Contao plugins into plugins/ (configurable via contao-component-dir) instead of vendor/.
   • Example composer.json:

     {
       "require": {
         "vendor/contao-plugin": "^1.0",
         "contao-components/installer": "^1.0"
       },
       "extra": {
         "contao-component-dir": "plugins"
       },
       "autoload": {
         "psr-4": {
           "App\\": "app/",
           "Contao\\Plugin\\": "plugins/"  // Map Contao namespaces
         }
       }
     }
     

2. Laravel Integration:
   • Autoloading: Classes in plugins/ are resolved via PSR-4 (test with composer dump-autoload).
   • Service Providers: Register Contao components in config/app.php if they need Laravel services (e.g., App\Services\ContaoBridge).
   • Database: Use Laravel migrations for Contao tables (avoid TL_* global functions).

Critical Gotchas

• Dependency Conflicts: Contao components may pull in old PHP/Composer versions. Pin them in composer.json:

  "config": {
    "platform-check": false,
    "preferred-install": "dist"
  }
  

• License Risks: LGPL-3.0 Contao components must not link to proprietary Laravel code. Use facades or dependency injection to decouple them.
• Debugging: Stack traces will show plugins/vendor/—add this to your IDE’s include path.

Migration Path

1. Pilot: Install a non-critical Contao component (e.g., a widget) and verify:
   • Autoloading works (new \Contao\Plugin\Widget()).
   • No conflicts with Laravel’s vendor/ (composer why-not).
2. Bridge Components: Wrap Contao-specific logic in Laravel ServiceProviders (e.g., convert TL_ROOT to config('contao.root')).
3. CI/CD: Add checks for:
   • composer validate (dependency conflicts).
   • php artisan optimize:clear (autoload cache).

Alternatives

• Laravel Packages: Rewrite Contao components as PSR-4 packages (long-term).
• Symlinks: Manually link plugins/ to vendor/ (risky for updates).
• Docker: Isolate Contao/Laravel in separate containers (complex).

Next Steps:

1. Week 1: Set up a test project with the installer and one Contao component.
2. Week 2: Document the workflow (e.g., ‘How to add a Contao component to Laravel’).
3. Week 3: Identify 2–3 high-priority Contao plugins to migrate.

Trade-off: This is not a silver bullet—it’s a temporary bridge. Plan to rewrite components as Laravel Packages within 6–12 months."*

For Developers

*"Here’s how to install and use Contao components in Laravel without pulling your hair out:

Step 1: Install the Package

composer require contao-components/installer

Add to your composer.json:

"extra": {
  "contao-component-dir": "plugins"
},
"autoload": {
  "psr-4": {
    "Contao\\": "plugins/"
  }
}

Run:

composer dump-autoload --optimize

Step 2: Add a Contao Component

composer require vendor/contao-plugin:^1.0

This installs the plugin to plugins/vendor/contao-plugin/.

Step 3: Use It in Laravel

• Classes: Autoloaded via PSR-4 (e.g., new \Contao\Plugin\MyClass()).
• Views: Place Blade templates in resources/views/plugins/vendor/contao-plugin/.
• Routes: Register in routes/web.php:

  Route::prefix('contao')->group(function () {
      require plugin_path('vendor/contao-plugin/routes.php');
  });
  

Common Issues & Fixes