Module Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require dahovitech/module-bundle
   

   Add to config/bundles.php:

   Dahovitech\ModuleBundle\ModuleBundle::class => ['all' => true],
   

2. Configure Create config/packages/modules.yaml:

   modules:
       path: '%kernel.project_dir%/modules'
       auto_discovery: true
   

3. Generate a Module Run the CLI command to scaffold a new module (e.g., Blog):

   php bin/console dahovitech:module:create Blog
   

   This creates a skeleton structure under modules/Blog/ with:

   • config/ (Symfony config)
   • src/ (PHP classes)
   • templates/ (Twig templates)
   • migrations/ (Doctrine migrations)
   • tests/ (PHPUnit tests)

4. Enable the Module Add to enabled_modules in modules.yaml:

   enabled_modules: ['Blog']
   

5. First Use Case: Route a Controller Define a route in modules/Blog/config/routes.yaml:

   blog_home:
       path: /blog
       controller: Dahovitech\ModuleBundle\Blog\Controller\BlogController::home
   

   Access via http://your-app/blog.

Implementation Patterns

Workflows

1. Module Creation & Isolation

   • Use dahovitech:module:create to scaffold a new module (e.g., User, Product).
   • Keep business logic, templates, and migrations self-contained in the module directory.
   • Example structure:

     modules/
       ├── User/
           ├── src/
               ├── Controller/
               ├── Entity/
               ├── Repository/
               ├── Service/
           ├── templates/
           ├── migrations/
           └── config/
     

2. Dependency Management

   • Declare module dependencies in modules/[ModuleName]/config/module.yaml:

     dependencies:
         - Blog
         - Media
     

   • The bundle resolves dependencies automatically during runtime (e.g., services, routes, or migrations).

3. Configuration

   • Override module configs via config/packages/modules_[ModuleName].yaml:

     modules:
         Blog:
             some_setting: 'value'
     

   • Access module-specific configs in controllers/services via:

     $this->getParameter('modules_blog.some_setting');
     

4. Routing

   • Define routes in modules/[ModuleName]/config/routes.yaml.
   • Prefix routes with the module name (e.g., blog_home) to avoid conflicts.
   • Use Twig namespacing in templates:

     {% extends '@Blog/base.html.twig' %}
     

5. Doctrine Integration

   • Place entities in modules/[ModuleName]/src/Entity/ (e.g., Post.php).
   • Migrations auto-detect the module namespace (e.g., 20230101000000_CreateBlogPosts.php).
   • Run migrations per-module:

     php bin/console doctrine:migrations:execute --module=Blog
     

6. Services & Autowiring

   • Register services in modules/[ModuleName]/src/[ModuleName]Module.php:

     public function getServices(): array
     {
         return [
             'services' => [
                 'Dahovitech\ModuleBundle\Blog\Service\PostService' => [],
             ],
         ];
     }
     

   • Autowire services in controllers:

     use Dahovitech\ModuleBundle\Blog\Service\PostService;
     
     public function __construct(PostService $postService) { ... }
     

7. Twig Namespacing

   • Use @ModuleName/template_name in Twig:

     {% include '@Blog/partials/header.html.twig' %}
     

   • Override global templates by placing them in templates/[ModuleName]/.

8. Commands & Events

   • Extend module functionality with custom commands:

     php bin/console dahovitech:module:command Blog:generate:posts
     

   • Listen to module events (e.g., ModuleEnableEvent) in modules/[ModuleName]/src/EventListener/.

Integration Tips

• Symfony Flex Recipes: Create a custom recipe for your module to enable composer require your/module (see Symfony Recipes).
• Testing: Run module-specific tests with:

  php bin/phpunit -G Blog
  

• Debugging: Use the dahovitech:module:list command to inspect enabled/disabled modules and their status.
• Deployment: Disable modules in disabled_modules during staging/production if needed:

  disabled_modules: ['Blog']
  

Gotchas and Tips

Pitfalls

1. Auto-Discovery Quirks

   • Modules must follow the exact structure (modules/[ModuleName]/) or be explicitly listed in enabled_modules.
   • Fix: Run php bin/console cache:clear after adding a new module.

2. Namespace Collisions

   • Avoid naming modules after existing Symfony bundles (e.g., Security).
   • Fix: Use unique names (e.g., AppBlog instead of Blog).

3. Doctrine Migrations

   • Migrations must include the module namespace in their class name (e.g., Blog\Migrations\...).
   • Fix: Use the dahovitech:module:migration:create command to generate properly namespaced migrations.

4. Circular Dependencies

   • The bundle does not support circular module dependencies (e.g., ModuleA depends on ModuleB, which depends on ModuleA).
   • Fix: Refactor dependencies or use shared services instead.

5. Cache Invalidation

   • Changes to modules.yaml or module configs require a cache clear:

     php bin/console cache:clear
     

6. Twig Template Overrides

   • Global templates (e.g., base.html.twig) in templates/ take precedence over module-specific templates.
   • Fix: Use @ModuleName/template.html.twig explicitly or rename module templates to avoid conflicts.

7. Service Overrides

   • Services defined in a module cannot override global services (e.g., twig).
   • Fix: Use tags or decorators for service extensions.

Debugging

1. Module Loading Issues

   • Check the dahovitech.module.list event in var/log/dev.log for errors.
   • Run php bin/console debug:container Dahovitech\ModuleBundle to inspect loaded modules.

2. Route Conflicts

   • Use php bin/console debug:router to list all routes and their module sources.
   • Prefix routes with the module name (e.g., blog.home) to avoid clashes.

3. Doctrine Entity Issues

   • Verify the orm namespace in modules/[ModuleName]/config/doctrine.yaml:

     orm:
         entity_managers:
             default:
                 mappings:
                     Blog:
                         is_bundle: false
                         dir: '%kernel.project_dir%/modules/Blog/src/Entity'
                         prefix: 'Dahovitech\ModuleBundle\Blog\Entity'
                         alias: Blog
     

4. CLI Command Errors

   • Ensure commands are registered in modules/[ModuleName]/src/[ModuleName]Module.php:

     public function getCommands(): array
     {
         return [
             'Dahovitech\ModuleBundle\Blog\Command\GeneratePostsCommand',
         ];
     }
     

Tips

1. Module Templates

   • Use the dahovitech:module:template command to generate boilerplate code:

     php bin/console dahovitech:module:template Blog Controller
     

2. Environment-Specific Configs

   • Override module configs per environment (e.g., config/packages/modules_dev.yaml):

     modules:
         Blog:
             debug: true
     

3. Performance

   • Enable caching for module metadata in modules.yaml:

     cache:
         enabled: true
         lifetime: 3600
     

4. Extending the Bundle

   • Override bundle behavior by creating a custom bundle that extends ModuleBundle:

     use Dahovitech\ModuleBundle\ModuleBundle as BaseModuleBundle;
     
     class CustomModuleBundle extends BaseModuleBundle
     {
         public function getPath(): string
         {
             return '%kernel.project_dir%/custom_modules';
         }
     }
     

5. Documentation

   • Generate API docs for module services/controllers using [NelmioApiDocBundle](https://github.com/nel