Module Installer Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel-based CVEPDB CMS project:

   composer require cvepdb-cms/module-installer
   

   Publish the package’s configuration (if available):

   php artisan vendor:publish --provider="CvepdbCms\ModuleInstaller\ModuleInstallerServiceProvider"
   

2. First Use Case Install a module via CLI:

   php artisan module:install <module-name>
   

   Verify installation by checking the modules table (if using a database-backed system) or the filesystem for module assets.

3. Where to Look First

   • Service Provider: CvepdbCms\ModuleInstaller\ModuleInstallerServiceProvider (registers commands, events, and bindings).
   • Console Command: CvepdbCms\ModuleInstaller\Console\InstallModuleCommand (core logic for installation).
   • Config File: config/module-installer.php (if published; defines paths, defaults, or module metadata).

Implementation Patterns

Core Workflows

1. Module Installation

   • CLI-Driven: Use php artisan module:install with optional flags (e.g., --force, --skip-migrations).
   • Programmatic: Call the installer via the service container:

     $installer = app(\CvepdbCms\ModuleInstaller\ModuleInstaller::class);
     $installer->install('module-name');
     

   • Event-Based: Listen for ModuleInstalled events to trigger post-install hooks (e.g., cache warming, notifications).

2. Module Uninstallation

   • Reverse of installation:

     php artisan module:uninstall <module-name>
     

   • Supports cleanup of:
     • Database tables (if --drop-tables flag is used).
     • Filesystem assets (configs, views, migrations).
     • Service provider registrations.

3. Dependency Management

   • Auto-Resolution: The installer may resolve module dependencies (e.g., composer require for PHP dependencies or module:install for CMS modules).
   • Validation: Check composer.json or a module.json manifest for dependencies before installation.

4. Post-Install Hooks

   • Database Migrations: Run pending migrations automatically or via a separate command.
   • Asset Compilation: Trigger npm run dev or php artisan asset:publish for module-specific assets.
   • Permissions: Set file/folder permissions (e.g., chmod -R 755 storage/module-cache).

Integration Tips

• Custom Module Structure Ensure modules follow the expected structure (e.g., ModuleName/ModuleNameServiceProvider.php, config/module.php). Example:

  /modules/
    ├── auth/
    │   ├── AuthServiceProvider.php
    │   ├── migrations/
    │   └── config/auth.php
  

• Service Provider Auto-Discovery Use ModuleInstaller::registerServiceProviders() to dynamically load module providers after installation.
• Configuration Merging Merge module-specific configs into the main config/ directory during installation:

  $this->mergeConfigFrom(
      $modulePath . '/config/module.php',
      'module.module-name'
  );
  

• Localization Support multi-language modules by copying language files to resources/lang/ during installation.

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Modules with identical class names (e.g., UserController) will cause autoloader conflicts.
   • Fix: Use unique module prefixes in class names (e.g., AuthUserController).

2. Database Conflicts

   • Installing a module with existing tables (without --force) may fail.
   • Fix: Use --drop-tables cautiously or implement blue-green migration strategies.

3. Circular Dependencies

   • Module A requiring Module B, which requires Module A, will deadlock.
   • Fix: Document dependencies clearly in module.json or use a dependency resolver.

4. Filesystem Permissions

   • Writing to storage/ or bootstrap/cache/ may fail if permissions are too restrictive.
   • Fix: Run php artisan module:install with a user owning the directories (e.g., sudo -u www-data).

5. Composer Autoloading

   • Modules added post-installation won’t be autoloaded until composer dump-autoload.
   • Fix: Run composer dump-autoload manually or hook it into the installer.

Debugging

• Verbose Output Use --verbose flag for detailed logs:

  php artisan module:install <name> --verbose
  

• Dry Runs Simulate installation without changes:

  php artisan module:install <name> --dry-run
  

• Event Listeners Temporarily disable listeners to isolate issues:

  Event::ignore(
      \CvepdbCms\ModuleInstaller\Events\ModuleInstalled::class
  );
  

Extension Points

1. Custom Installers Extend the base installer for module-specific logic:

   class CustomInstaller extends \CvepdbCms\ModuleInstaller\ModuleInstaller {
       protected function postInstallHooks($module) {
           // Add custom logic (e.g., API key setup)
       }
   }
   

2. Pre/Post Hooks Bind events to extend behavior:

   Event::listen(\CvepdbCms\ModuleInstaller\Events\ModuleInstalling::class, function ($event) {
       // Pre-install logic
   });
   

3. Module Metadata Define custom metadata in module.json:

   {
       "name": "auth",
       "description": "Authentication module",
       "dependencies": ["database"],
       "hooks": {
           "post-install": "php artisan auth:publish"
       }
   }
   

4. Testing Mock the installer in tests:

   $installer = Mockery::mock(\CvepdbCms\ModuleInstaller\ModuleInstaller::class);
   $installer->shouldReceive('install')->once();
   

Config Quirks

• Path Resolution The installer may use base_path('modules') by default. Override in config:

  'paths' => [
      'modules' => base_path('custom-modules'),
  ],
  

• Environment Checks Some modules may require specific environments (e.g., app() checks for config('app.env') === 'local'). Handle this in the installer’s supports() method.

Performance

• Batch Operations For bulk installs, use a queue job to avoid timeouts:

  InstallModulesJob::dispatch(['module1', 'module2']);
  

• Caching Cache module metadata to avoid repeated filesystem scans:

  Cache::remember('module-metadata', now()->addHours(1), function () {
      return ModuleInstaller::getAllModules();
  });