Laravel Easy Modules Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require kadevland/laravel-easy-modules
   php artisan easy-modules:install
   

   • Follow prompts to configure module storage paths (default: modules/).

2. First Module Creation

   php artisan easy-modules:make Blog --type=clean
   

   • --type=clean generates a Clean Architecture template (alternatives: basic, resourceful).

3. Verify Structure

   • Check modules/Blog/ for generated files:

     Blog/
     ├── Domain/
     ├── Application/
     ├── Infrastructure/
     ├── Presentation/
     ├── config/
     ├── routes/
     └── ...
     

First Use Case

Generate a module for a new feature (e.g., UserProfile):

php artisan easy-modules:make UserProfile --type=resourceful

• This creates a module with:
  • Resource controller (UserProfileController)
  • Migration (user_profiles table)
  • Routes (web.php or api.php)
  • Views (if using resourceful type).

Implementation Patterns

Core Workflows

1. Modular Feature Development

   • Create a module:

     php artisan easy-modules:make Posts --type=clean
     

   • Extend functionality:

     php artisan easy-modules:make-command Posts/GenerateSitemap
     php artisan easy-modules:make-job Posts/ProcessPost
     

   • Register providers/services: Edit modules/Posts/Providers/ModuleServiceProvider.php to bind interfaces to implementations.

2. Integration with Existing Code

   • Access module services:

     // In a controller or service
     $postService = app(\Modules\Posts\Domain\Services\PostService::class);
     

   • Load module routes:

     // In a route file
     \Modules\Posts\Presentation\Http\Routes\web();
     

3. Database Migrations

   • Run migrations for a module:

     php artisan migrate --path=modules/Posts/Database/Migrations
     

   • Share migrations across modules:

     php artisan easy-modules:publish-migrations Posts
     

4. Testing

   • Unit tests: Place in modules/Posts/Tests/Unit/.
   • Feature tests: Place in modules/Posts/Tests/Feature/.
   • Run tests:

     php artisan test --module=Posts
     

Customization Patterns

1. Override Default Templates

   • Publish and customize stubs:

     php artisan vendor:publish --tag=easy-modules-stubs
     

   • Edit stubs in resources/views/vendor/easy-modules/stubs/.

2. Module Dependencies

   • Declare dependencies in modules/Posts/composer.json:

     "require": {
         "kadevland/laravel-easy-modules": "^2.0"
     },
     "extra": {
         "easy-modules": {
             "depends": ["Auth"]
         }
     }
     

   • Run composer update in the module directory.

3. Dynamic Module Loading

   • Load modules conditionally in config/easy-modules.php:

     'enabled_modules' => [
         'Posts' => env('ENABLE_POSTS_MODULE', true),
         'Blog' => env('ENABLE_BLOG_MODULE', false),
     ],
     

4. API/Resourceful Modules

   • Generate API endpoints:

     php artisan easy-modules:make Posts/Api --type=resourceful --api
     

   • Customize API responses in modules/Posts/Presentation/Http/Resources/.

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Issue: Modules with similar class names (e.g., User vs. Users) can cause autoloading conflicts.
   • Fix: Use fully qualified namespaces:

     use Modules\Users\Domain\Entities\User as UserEntity;
     use Modules\User\Domain\Entities\User as AdminUser;
     

   • Prevention: Avoid overlapping names during module creation.

2. Service Provider Registration

   • Issue: Forgetting to register the module’s ModuleServiceProvider in config/app.php.
   • Fix: Run:

     php artisan easy-modules:register Posts
     

   • Tip: Use the --all flag to register all modules:

     php artisan easy-modules:register --all
     

3. Migration Paths

   • Issue: Migrations not found during php artisan migrate.
   • Fix: Ensure modules/Posts/Database/Migrations is in config/database.php under migrations:

     'migrations' => [
         database_path('migrations'),
         modules_path('*/Database/Migrations'),
     ],
     

4. Route Caching

   • Issue: Routes not reflecting changes after module updates.
   • Fix: Clear route cache:

     php artisan route:clear
     

   • Tip: Disable caching during development in config/easy-modules.php:

     'cache_routes' => env('APP_ENV') !== 'local',
     

5. Composer Autoload

   • Issue: New classes not autoloaded after adding files.
   • Fix: Run:

     composer dump-autoload
     

   • Tip: Use --optimize for production:

     composer dump-autoload --optimize
     

Debugging Tips

1. Module Not Found Errors

   • Verify the module is listed in config/easy-modules.php under modules.
   • Check for typos in module names (case-sensitive).

2. Artisan Command Issues

   • Debug: Run with -v for verbose output:

     php artisan easy-modules:make Posts --type=clean -v
     

   • Common Causes:
     • Missing dependencies (e.g., laravel/framework).
     • Incorrect stub paths (check vendor:publish step).

3. Clean Architecture Quirks

   • Domain Layer: Ensure entities/interfaces are in Domain/ and implementations in Infrastructure/.
   • Circular Dependencies: Avoid Application/ depending directly on Infrastructure/. Use interfaces in Domain/ as contracts.

4. Testing Modules

   • Isolate Tests: Use --module flag to run only relevant tests:

     php artisan test --module=Posts --filter=UserProfileTest
     

   • Mock External Modules: Use Laravel’s partialMock for shared services:

     $this->partialMock(\Modules\Auth\Domain\Services\AuthService::class, function ($mock) {
         $mock->shouldReceive('checkPermission')->andReturn(true);
     });
     

Extension Points

1. Custom Module Types

   • Extend the generator by creating a custom stub:

     php artisan vendor:publish --tag=easy-modules-stubs
     

   • Add a new stub in resources/views/vendor/easy-modules/stubs/module-types/custom/.
   • Register the type in config/easy-modules.php:

     'module_types' => [
         'custom' => [
             'path' => 'custom',
             'description' => 'Custom module template',
         ],
     ],
     

2. Post-Creation Hooks

   • Override module creation logic by publishing the event listener:

     php artisan vendor:publish --tag=easy-modules-events
     

   • Extend ModulesCreated event in app/Listeners/.

3. Dynamic Module Configuration

   • Load module-specific config dynamically:

     // In a service provider
     $config = require module_path('Posts/config/posts.php');
     

   • Publish module config:

     php artisan easy-modules:publish-config Posts
     

4. Module Isolation

   • Disable a Module: Set 'enabled' => false in config/easy-modules.php.
   • Uninstall a Module: Use the built-in uninstaller:

     php artisan easy-modules:uninstall Posts --force
     

     • Warning: This deletes the module directory. Backup first.

Performance Tips

1. Lazy-Loading Modules

   • Use eager_load_modules in config/easy-modules.php to defer loading:

     'eager_load_modules' => false,
     

   • Load modules on-demand in service providers.

2. Optimize Autoloading

   • Exclude module tests from autoload in composer.json:

     "autoload-dev": {
         "psr-4": {
             "Modules\\": "modules/"
         },
         "exclude-from-classmap": [
             "modules/*/Tests/"
         ]
     }
     

3. Route Optimization

   • Group module routes in a single file