Plugin Installer Laravel Package

Getting Started

Minimal Setup

1. Install the Package Add the installer to your project’s composer.json under extra.installer-plugins:

   {
     "extra": {
       "installer-plugins": {
         "craftcms/plugin-installer": {
           "types": ["craft-plugin"],
           "file": "vendor/craftcms/plugin-installer/src/PluginInstaller.php"
         }
       }
     }
   }
   

   Run composer update to apply.

2. First Use Case: Installing a Plugin Install a Craft CMS plugin via Composer:

   composer require vendor/plugin-name
   

   The installer will automatically detect and install the plugin into Craft’s plugins/ directory (e.g., craft/config/plugins/).

3. Where to Look First

   • Craft CMS Docs: Plugin Development for plugin structure expectations.
   • Package Source: GitHub (if available) for edge cases or customization.
   • Composer Logs: Check composer.json of installed plugins for type: "craft-plugin" metadata.

Implementation Patterns

Workflow: Plugin Development & Distribution

1. Plugin Structure Ensure your plugin follows Craft’s conventions:

   /vendor/
     /your-vendor/
       /plugin-name/
         Plugin.php          # Main plugin class (extends `craft\base\Plugin`)
         services.php        # Service definitions
         variables.php       # Twig variables
         config.php          # Default settings
   

   • Key Files:
     • Plugin.php: Must implement getName(), getVersion(), and init().
     • composer.json: Include "type": "craft-plugin" and "extra": { "installer-name": "vendor/plugin-name" }.

2. Local Development

   • Use composer require vendor/plugin-name --dev for local testing.
   • Symlink the plugin for live reloading:

     ln -s /path/to/plugin-name /path/to/craft/cms/web/craft/config/plugins/
     

3. CI/CD Integration

   • Automated Testing: Run composer install in CI to verify plugin installation.
   • Deployment: Use composer install --prefer-dist --no-dev in production to avoid dev dependencies.

4. Post-Install Hooks Override Craft’s plugin installation logic by publishing assets or running migrations:

   // In Plugin.php
   public function init()
   {
       parent::init();
       Craft::$app->getAssetManager()->publishAssetPath(
           $this,
           'your-vendor/plugin-name/assets',
           'plugins/your-vendor-plugin-name/assets'
       );
   }
   

Gotchas and Tips

Pitfalls

1. Plugin Not Detected

   • Cause: Missing "type": "craft-plugin" in composer.json or incorrect installer-name.
   • Fix: Verify the plugin’s composer.json and run composer dump-autoload.

2. Permission Issues

   • Cause: Composer lacks write access to craft/config/plugins/.
   • Fix: Set correct permissions:

     chmod -R 755 craft/config/plugins/
     

3. Plugin Overwrites

   • Cause: Multiple plugins with the same namespace or conflicting files.
   • Fix: Use unique vendor names and avoid naming conflicts (e.g., yourcompany/plugin-name).

4. Craft Version Mismatch

   • Cause: Plugin requires Craft 4.x but is installed on 3.x (or vice versa).
   • Fix: Enforce version constraints in composer.json:

     "require": {
         "craftcms/cms": "^4.0"
     }
     

Debugging

• Composer Verbose Mode: Run composer install -v to trace installation steps.
• Craft Logs: Check storage/logs/ for plugin initialization errors.
• Plugin Isolation: Test plugins in a fresh Craft install to rule out conflicts.

Extension Points

1. Custom Installer Logic Extend the installer by creating a custom PluginInstaller class:

   // In your plugin’s composer.json
   "extra": {
       "installer-name": "your-vendor/custom-installer"
   }
   

   Implement Composer\Package\PluginInstallerInterface.

2. Post-Install Scripts Use Composer scripts to run migrations or publish assets:

   "scripts": {
       "post-install-cmd": [
           "@craft install-plugin your-vendor/plugin-name"
       ]
   }
   

3. Multi-Plugin Projects For monorepos or multi-plugin setups, use composer.json aliases:

   composer require vendor/plugin-a vendor/plugin-b --with-all-dependencies
   

Pro Tips

• Plugin Templates: Use Craft’s plugin template as a starting point.
• Asset Optimization: Publish assets during installation to avoid runtime errors:

  // In Plugin.php
  public function init()
  {
      $this->setComponents([
          'assets' => \craft\web\AssetManager::class,
      ]);
      $this->assets->publishResourceLocation();
  }
  

• Local Development Shortcut: Use composer create-project vendor/plugin-name to scaffold a new plugin.