Generator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avro/generator-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Avro\GeneratorBundle\AvroGeneratorBundle::class => ['all' => true],
   ];
   

2. First Use Case: Generate a basic bundle skeleton:

   php app/console avro:generate:bundle --name=Acme/DemoBundle
   

   • Follow the prompts or specify arguments directly (e.g., --dir=src).

3. Key Files:

   • Templates: Located in Resources/views/AvroGeneratorBundle/ (extend or override these).
   • Configuration: Define generators in config/packages/avro_generator.yaml (or config/avro_generator.yaml in older Symfony versions).

Implementation Patterns

Core Workflows

1. Entity-to-Code Generation:

   • Map Doctrine entities to templates via YAML config:

     # config/packages/avro_generator.yaml
     avro_generator:
         generators:
             entity_to_crud:
                 template: 'AvroGeneratorBundle:Entity:CRUD'
                 mapping:
                     Acme\DemoBundle\Entity\Post: 'AcmeDemoBundle'
     

   • Run:

     php app/console avro:generate:entity-to-crud
     

2. Custom Templates:

   • Create a template in templates/AvroGeneratorBundle/YourNamespace/YourTemplate.twig:

     {# templates/AvroGeneratorBundle/Custom/Service.twig #}
     namespace {{ namespace }};
     class {{ class_name }} extends {{ parent_class }}
     {
         public function __construct({{ dependencies }})
         {
             // ...
         }
     }
     

   • Reference it in config:

     generators:
         custom_service:
             template: 'Custom:Service'
             mapping: { Acme\DemoBundle\Entity\Post: 'PostService' }
     

3. Incremental Generation:

   • Use --dry-run to preview changes:

     php app/console avro:generate:bundle --dry-run
     

   • Override existing files with --force (caution: use sparingly).

4. Integration with Workflows:

   • Post-Deploy: Hook into post-deploy in composer.json to auto-generate code:

     "scripts": {
         "post-install-cmd": [
             "php bin/console avro:generate:entity-to-crud --env=prod"
         ]
     }
     

   • CI/CD: Run generators in pipelines to ensure consistency across environments.

Gotchas and Tips

Pitfalls

1. Template Inheritance:

   • Twig templates must extend a base template (e.g., AvroGeneratorBundle:Base:template.html.twig) to avoid rendering issues.
   • Example:

     {# Correct #}
     {% extends 'AvroGeneratorBundle:Base:template.html.twig' %}
     {% block content %}{{ content }}{% endblock %}
     

2. Namespace Collisions:

   • Ensure mapping keys in YAML use fully qualified class names (e.g., Acme\DemoBundle\Entity\Post), not short names.
   • Avoid reusing template names across generators (e.g., two generators with template: 'Entity:CRUD').

3. Doctrine Metadata Cache:

   • Regenerate metadata cache after entity changes:

     php app/console doctrine:cache:clear-metadata
     

   • If generators fail silently, check var/cache/dev/doctrine/orm/Proxies/__CG__....

4. File Overwrites:

   • The --force flag silently overwrites files. Use --dry-run first to inspect changes:

     php app/console avro:generate:bundle --dry-run --force
     

Debugging Tips

1. Enable Twig Debugging: Add to config/packages/twig.yaml:

   twig:
       debug: true
       strict_variables: true
   

   • Check Twig errors in var/log/dev.log.

2. Generator Logs:

   • Set debug: true in avro_generator config to log template rendering:

     avro_generator:
         debug: true
     

3. Template Variables:

   • Debug available variables in templates by dumping them:

     {% dump _context.getAvailableFunctions() %}
     {% dump entity.metadata %}
     

Extension Points

1. Custom Command: Extend the base generator command:

   // src/Command/CustomGenerateCommand.php
   namespace App\Command;
   use Avro\GeneratorBundle\Command\GenerateCommand;
   class CustomGenerateCommand extends GenerateCommand {
       protected function configure() {
           $this->setName('avro:generate:custom');
       }
       protected function execute(InputInterface $input, OutputInterface $output) {
           $this->generate('custom_service', $output);
       }
   }
   

2. Dynamic Templates: Use Twig’s include to modularize templates:

   {% include 'AvroGeneratorBundle:Parts:useStatements.twig' %}
   

3. Pre/Post-Generation Hooks: Override the generator service to add logic:

   # config/services.yaml
   services:
       Avro\GeneratorBundle\Generator\Generator:
           class: App\Service\CustomGenerator
           decorates: 'avro_generator.generator'
   

   // src/Service/CustomGenerator.php
   use Avro\GeneratorBundle\Generator\Generator as BaseGenerator;
   class CustomGenerator extends BaseGenerator {
       public function generate($name, OutputInterface $output) {
           // Pre-generation logic
           parent::generate($name, $output);
           // Post-generation logic
       }
   }
   

4. Environment-Specific Config: Use Symfony’s environment-aware config (e.g., config/packages/avro_generator_{env}.yaml) to toggle generators:

   # config/packages/avro_generator_prod.yaml
   avro_generator:
       generators:
           entity_to_crud: ~  # Disabled in prod