Getting Started

Minimal Steps for Laravel Integration

Install the Package:

composer require contao-components/installer

Add to your project’s composer.json:

"extra": {
  "contao-component-dir": "plugins"  // Custom directory for Contao components
}

Create a Contao Component:

Publish a package with "type": "contao-component" in its composer.json:

{
  "name": "vendor/contao-widget",
  "type": "contao-component",
  "require": {
    "contao-components/installer": "^1.0"
  }
}

Require the Component in Laravel:
```
composer require vendor/contao-widget
```
Verify installation in plugins/vendor/.

Configure Autoloading: Update composer.json to include Contao namespaces:

"autoload": {
  "psr-4": {
    "App\\": "app/",
    "Vendor\\Contao\\": "plugins/vendor/"  // Map Contao component namespace
  }
}

Run:

composer dump-autoload

Test Basic Functionality:

use Vendor\Contao\Widget\ExampleClass;

$instance = new ExampleClass(); // Verify no autoload errors

Implementation Patterns

Workflows for Laravel Developers

1. Component Development Workflow

Local Development:
- Develop Contao components in separate repos with "type": "contao-component".
- Use composer install in the component repo to test locally.
Integration with Laravel:
- Require the component in Laravel’s composer.json and run composer update.
- Test autoloading and functionality in Laravel’s environment.

2. Dependency Management

Shared Dependencies: If a Contao component requires a shared library (e.g., monolog/monolog), ensure Laravel’s composer.json includes it to avoid conflicts.
```
"require": {
  "monolog/monolog": "^3.0",
  "vendor/contao-widget": "^1.0"
}
```
Version Pinning: Pin Contao component versions to avoid unexpected updates:
```
"require": {
  "vendor/contao-widget": "1.0.0"
}
```

3. Autoloading Strategies

PSR-4 Mapping: Explicitly map Contao component namespaces in composer.json:

"autoload": {
  "psr-4": {
    "Vendor\\Contao\\": "plugins/vendor/src/"
  }
}

Files Autoloading: For standalone files (e.g., Contao’s config/autoload.php), add:
```
"autoload": {
  "files": ["plugins/vendor/config/autoload.php"]
}
```

4. Laravel Service Integration

Register Contao Components: Bind Contao classes to Laravel’s container in AppServiceProvider:

public function register()
{
    $this->app->bind(
        \Vendor\Contao\Widget\ExampleClass::class,
        \Vendor\Contao\Widget\ExampleClass::class
    );
}

Facade Integration: Create a facade for Contao-specific functionality:

// ContaoWidgetFacade.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class ContaoWidgetFacade extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'contao.widget';
    }
}

'aliases' => [
    'ContaoWidget' => App\Facades\ContaoWidgetFacade::class,
],

5. Database and Configuration

Migrations: If Contao components require database tables, create Laravel migrations that mirror Contao’s DCA structure:

Schema::create('tl_contao_widgets', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->timestamps();
});

Configuration: Load Contao’s config.php or system.php in Laravel’s bootstrap:

// In AppServiceProvider's boot()
$this->loadContaoConfig();

private function loadContaoConfig()
{
    if (file_exists($path = base_path('plugins/vendor/config/config.php'))) {
        require $path;
    }
}

6. Routing

Contao Frontend Routes: Use Laravel’s routing to proxy requests to Contao components:

Route::prefix('contao')->group(function () {
    Route::get('/widget/{id}', function ($id) {
        // Load Contao component and render
        return view('contao.widget', ['id' => $id]);
    });
});

Admin Panel Integration: Extend Laravel’s admin routes to include Contao backend modules:

Route::middleware(['web', 'auth'])->prefix('contao')->group(function () {
    Route::get('/backend', [ContaoBackendController::class, 'index']);
});

Gotchas and Tips

Pitfalls and Debugging

1. Autoloading Failures

Symptom: Class not found errors for Contao components.
Cause: Missing or incorrect PSR-4 mapping in composer.json.
Fix: Run composer dump-autoload --optimize and verify the namespace path in vendor/composer/autoload_psr4.php. Ensure the contao-component-dir in composer.json matches the actual directory.

2. Dependency Conflicts

Symptom: Composer install fails with version conflicts (e.g., phpunit/phpunit).
Cause: Contao components or Laravel require incompatible versions of the same package.

Fix: Use composer why-not vendor/package to diagnose conflicts. Override dependencies in composer.json:

"conflict-resolution": {
    "prefer-lowest": true,
    "owned": {
        "monolog/monolog": "3.0.0"
    }
}

3. Namespace Collisions

Symptom: Class 'Vendor\Contao\ClassName' not found despite correct autoloading.
Cause: Contao components use the same namespace as Laravel or another package.
Fix: Rename the Contao component’s namespace or use aliases in Laravel’s config/app.php:
```
'aliases' => [
    'ContaoWidget' => Vendor\RenamedContaoNamespace\Widget::class,
],
```

4. Global State Conflicts

Symptom: Contao components rely on global functions (e.g., TL_ROOT, $GLOBALS['TL_CONFIG']) that Laravel overrides.

Fix: Initialize Contao’s globals in a Laravel service provider:

public function boot()
{
    if (!defined('TL_ROOT')) {
        define('TL_ROOT', base_path('plugins/vendor'));
    }
    if (!isset($GLOBALS['TL_CONFIG'])) {
        $GLOBALS['TL_CONFIG'] = [];
    }
}

5. Database Schema Mismatches

Symptom: Contao components expect tables that don’t exist in Laravel’s migrations.

Fix: Create Laravel migrations that replicate Contao’s DCA structure. Example for a tl_contao_widgets table:

Schema::create('tl_contao_widgets', function (Blueprint $table) {
    $table->id();
    $table->string('title')->nullable();
    $table->text('content')->nullable();
    $table->integer('pid')->unsigned()->nullable();
    $table->integer('sorting')->unsigned()->default(0);
    $table->timestamps();
});

6. Caching Issues

Symptom: Changes to Contao components aren’t reflected after composer update.
Cause: Laravel’s cache or Composer’s autoloader cache.

Fix: Clear Laravel caches:

php artisan cache:clear
php artisan view:clear
php artisan config:clear

Rebuild Composer autoloader:

composer dump-autoload

Configuration Quirks

1. Custom Installer Path

The contao-component-dir in composer.json must be an absolute path relative to the project root. Example:
```
"extra": {
  "contao-component-dir": "plugins/vendor"
}
```

Installer Laravel Package