Module Manager Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the package:

   composer require nasirkhan/module-manager
   

2. Publish core module assets (if needed):

   php artisan vendor:publish --tag=module-manager-config
   

3. Check module status to verify installation:

   php artisan module:status
   

First Use Case: Enable and Test a Module

1. Enable a module (e.g., Post):

   php artisan module:enable Post
   

2. Verify dependencies are satisfied:

   php artisan module:dependencies Post
   

3. Run migrations for the module:

   php artisan module:track-migrations Post
   php artisan migrate
   

Key Files to Review

• Modules/ directory (auto-generated after publishing).
• module.json (module metadata and dependencies).
• config/module-manager.php (published config).

Implementation Patterns

Workflow: Developing a New Module

1. Scaffold a module:

   php artisan module:build MyModule
   

   • Generates Modules/MyModule/ with standard Laravel structure.
2. Define dependencies in module.json:

   {
     "requires": ["Category", "Tag"]
   }
   

3. Publish assets for customization:

   php artisan module:publish MyModule
   

4. Track migrations after updates:

   php artisan module:track-migrations MyModule --force
   

Integration with Laravel Features

• Service Providers: Modules auto-register providers in Modules/{Module}/Providers/.
• Routes: Use Route::module('post', function () { ... }) or publish routes via module:publish.
• Middleware: Register middleware in Http/Middleware/ and bind to routes.
• Testing: Generate tests with:

  php artisan module:make-test MyModule UserTest --unit
  

Dependency Management

• Check dependencies before enabling:

  php artisan module:dependencies MyModule
  

• Programmatic check (in code):

  $service = app(\Nasirkhan\ModuleManager\Services\ModuleVersion::class);
  if (!$service->dependenciesSatisfied('MyModule')) {
      // Handle missing dependencies
  }
  

Migration Workflow

1. Detect updates after composer update:

   php artisan module:detect-updates MyModule
   

2. Publish new migrations:

   php artisan vendor:publish --tag=my-module-migrations
   

3. Run migrations:

   php artisan migrate
   

Priority-Based Loading

• Set priority in module.json to control load order (higher = loads first).
• Retrieve ordered modules programmatically:

  $modules = app(\Nasirkhan\ModuleManager\Services\ModuleVersion::class)
      ->getModulesByPriority();
  

Gotchas and Tips

Common Pitfalls

1. Namespace Conflicts:

   • After publishing, run:

     composer dump-autoload
     php artisan config:clear
     

   • Ensure Modules/{Module}/ namespaces match the published structure.

2. Missing Dependencies:

   • Use module:dependencies to debug. Example output:

     [ERROR] Module "Post" requires "Category" (v1.0.0), but found v0.9.0.
     

   • Fix by updating the dependent module or adjusting module.json.

3. Migrations Not Detected:

   • Force-track migrations:

     php artisan module:track-migrations MyModule --force
     

   • Clear migration cache:

     php artisan cache:clear
     

4. Routes Not Loading:

   • Verify the module is enabled (module:status).
   • Check if routes are published to Modules/{Module}/routes/.

5. Circular Dependencies:

   • The package throws an error if module.json contains circular requires (e.g., A requires B, B requires A).

Debugging Tips

• Check module status details:

  php artisan module:status MyModule --verbose
  

• Compare published vs. vendor versions:

  php artisan module:diff MyModule --detailed
  

• Enable debug mode in config/module-manager.php:

  'debug' => env('MODULE_MANAGER_DEBUG', false),
  

Extension Points

1. Custom Module Build Templates:

   • Override stubs in resources/stubs/module-manager/ (if using Laravel Starter).
   • Extend the module:build command by publishing its templates:

     php artisan vendor:publish --tag=module-manager-stubs
     

2. Hooks for Lifecycle Events:

   • Listen for module events (e.g., ModuleEnabled, ModuleDisabled) via Laravel’s event system.
   • Example:

     use Nasirkhan\ModuleManager\Events\ModuleEnabled;
     
     ModuleEnabled::subscribe(function ($event) {
         Log::info("Module {$event->module} enabled!");
     });
     

3. Custom Migration Tracking:

   • Extend MigrationTracker to add pre/post-migration hooks:

     $tracker = app(\Nasirkhan\ModuleManager\Services\MigrationTracker::class);
     $tracker->extend(function ($module) {
         // Custom logic before tracking
     });
     

Performance Considerations

• Disable unused modules to reduce autoload overhead:

  php artisan module:disable UnusedModule
  

• Use --force sparingly for module:track-migrations to avoid accidental overwrites.

Configuration Quirks

• Priority Collisions:
  • If two modules have the same priority, the alphabetically first one loads first.
• Default Enabled State:
  • Modules are disabled by default after publishing. Enable explicitly:

    php artisan module:enable MyModule
    

Pro Tips

1. Backup Before Major Updates:
   • Use module:diff to compare versions before updating:

     php artisan module:diff MyModule --detailed > backup/diff.txt
     

2. Automate Testing:
   • Generate and run module-specific tests in CI:

     php artisan module:make-test MyModule FeatureTest
     php artisan test --filter=MyModule
     

3. Leverage module.json Keywords:
   • Use keywords for internal tagging (e.g., "keywords": ["admin", "ui"]) to filter modules programmatically.