Composer Plugin Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Plugin: Add the plugin to your root project’s composer.json (not the module’s) under require-dev:

   "require-dev": {
       "contao-community-alliance/composer-plugin": "~3.0"
   }
   

   Run composer require contao-community-alliance/composer-plugin --dev.

2. Configure a Contao 3 Module: In your module’s composer.json, set:

   {
       "type": "contao-module",
       "require": {
           "contao/core-bundle": "~3.5",
           "contao-community-alliance/composer-plugin": "~2.4 || ~3.0"
       },
       "extra": {
           "contao": {
               "sources": {
                   "": "system/modules/your-module-name"
               }
           }
       }
   }
   

3. Install the Module: Run composer require vendor/package-name in your root project. The plugin will:

   • Copy files to system/modules/your-module-name.
   • Symlink userfiles (if configured).
   • Execute runonce scripts (if specified).

4. Verify Installation: Check system/modules/ for the module files and confirm Contao detects it via the backend.

First Use Case: Adding a Contao 3 Module to a Laravel/Contao Hybrid Project

If your Laravel project integrates Contao 3 modules (e.g., for legacy support), use this plugin to:

• Automate module installation without manual symlinking.
• Ensure system/modules/ is populated correctly for Contao’s autoloader.
• Example workflow:

  composer require contao-community-alliance/composer-plugin --dev
  composer require vendor/contao-legacy-module
  php artisan contao:clear-cache  # If using a Contao bridge
  

Implementation Patterns

Core Workflows

1. Module Development Workflow

• Structure Your Module: Organize files in a src/ folder (for PSR-4) or flat structure (for legacy Contao autoloading). Example:

  src/
    system/
      modules/
        your-module/
          config/
          dca/
          templates/
  

• Configure composer.json:

  "extra": {
      "contao": {
          "sources": {
              "src/system/modules/your-module": "system/modules/your-module"
          },
          "userfiles": {
              "src/system/modules/your-module/files": "your-module/files"
          },
          "runonce": [
              "src/system/modules/your-module/runonce/update_db.php"
          ]
      }
  }
  

• Autoloading: Use PSR-4 for modern Laravel compatibility:

  "autoload": {
      "psr-4": {
          "Vendor\\Module\\": "src/"
      }
  }
  

2. Hybrid Contao 3/4 Projects

• Dual Version Support: Require both Contao versions in composer.json:

  "require": {
      "contao/core-bundle": "~3.5 || ~4.1",
      "contao-community-alliance/composer-plugin": "~2.4 || ~3.0"
  }
  

• Conditional Logic: Use Contao’s TL_CONFIG or Laravel’s environment checks to route logic:

  if (version_compare(\Contao\CoreBundle\ContaoCoreBundle::VERSION, '4.0', '<')) {
      // Contao 3 logic
  }
  

3. CI/CD Integration

• Automate Testing: Add a composer post-install-cmd script to verify module installation:

  "scripts": {
      "post-install-cmd": [
          "@contao-install",
          "@php artisan contao:check-modules"
      ]
  }
  

• Docker/Server Setup: Ensure symlink support is enabled (Contao 4 requirement):

  RUN sysctl -w fs.protected_symlinks=0  # For some Linux distros
  

Integration Tips

Laravel-Specific Considerations

1. Filesystem Conflicts:

   • Contao’s system/modules/ may conflict with Laravel’s storage/ or bootstrap/cache/.
   • Solution: Use Laravel’s public_path() or storage_path() to map Contao’s files/ directory:

     // In a Contao module's runonce script
     $filesDir = \Contao\System::getContainer()->getParameter('kernel.project_dir') . '/storage/app/public/contao-files';
     symlink($filesDir, TL_ROOT . '/files');
     

2. Autoloading Conflicts:

   • Contao 3 modules may use global namespaces (e.g., class MyModule).
   • Solution: Prefix classes or use Laravel’s ClassLoader to merge autoloaders:

     // In a service provider
     $loader = require __DIR__ . '/../../vendor/autoload.php';
     $loader->addPsr4('Vendor\\Module\\', __DIR__ . '/../../src/system/modules/your-module');
     

3. Database Migrations:

   • Contao modules often include runonce scripts for DB updates.
   • Solution: Sync with Laravel migrations:

     // In a runonce script
     if (Schema::hasTable('tl_your_module')) {
         Schema::table('tl_your_module', function (Blueprint $table) {
             $table->string('new_field')->nullable()->after('old_field');
         });
     }
     

Advanced Patterns

1. Dynamic Module Loading: Use Laravel’s service providers to lazy-load Contao modules:

   // ContaoServiceProvider.php
   public function register()
   {
       if (file_exists($this->app->basePath('system/modules/your-module/config/autoload.php'))) {
           require $this->app->basePath('system/modules/your-module/config/autoload.php');
       }
   }
   

2. Composer Scripts for Contao: Extend the plugin’s behavior with custom scripts:

   "scripts": {
       "contao-post-install": [
           "php artisan contao:optimize",
           "php artisan contao:clear-cache"
       ]
   }
   

   Trigger via:

   composer contao-post-install
   

Gotchas and Tips

Pitfalls

1. Plugin Not Installed in Root Project:

   • Error: The contao-composer-plugin is not installed.
   • Fix: Ensure the plugin is in the root project’s composer.json under require-dev, not the module’s.

2. Symlink Failures:

   • Error: Failed to create symlink: Operation not permitted.
   • Fix:
     • Enable symlinks in PHP (php.ini): disable_functions = "".
     • For Docker, add RUN sysctl -w fs.protected_symlinks=0.
     • Use absolute paths in sources:

       "sources": {
           "src/system/modules/your-module": "system/modules/your-module"
       }
       

3. Contao 4 vs. 3 Confusion:

   • Error: Module works in Contao 4 but fails in Contao 3 (or vice versa).
   • Fix:
     • Use version_compare(\Contao\CoreBundle\ContaoCoreBundle::VERSION, '4.0', '<') to branch logic.
     • For Contao 4, prefer Symfony bundles over contao-module type.

4. Runonce Scripts Not Executing:

   • Error: runonce files are ignored.
   • Fix:
     • Ensure paths in runonce are relative to the module root (not vendor/).
     • Verify the runonce section is under extra.contao:

       "extra": {
           "contao": {
               "runonce": ["path/to/script.php"]
           }
       }
       

5. Userfiles Not Copying:

   • Error: Files in userfiles section are missing after install.
   • Fix:
     • Use absolute source paths (relative to the module root):

       "userfiles": {
           "src/system/modules/your-module/files/images": "your-module/images"
       }
       

     • Ensure the target directory exists in Contao’s files/ folder.

6. Namespace Collisions:

   • Error: Class 'YourModule' not found in Contao 3.
   • Fix:
     • Avoid global namespaces; use PSR-4:

       "autoload": {
           "psr-4": {
               "Vendor\\Module\\": "src/"
           }
       }
       

     • Register the autoloader in Contao’s `config