Fast Show Generator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acseo/fast-show-generator-bundle
   

   Ensure your config/bundles.php includes:

   return [
       // ...
       ACSEO\FastShowGeneratorBundle\ACSEOFastShowGeneratorBundle::class => ['all' => true],
   ];
   

2. Choose Configuration Method

   • Annotation: Add the annotation use statement to your entity:

     use ACSEO\FastShowGeneratorBundle\Annotations\Show;
     

   • YAML: Create a config file at:

     src/ACSEO/Bundle/MyBundle/Resources/config/fastshowgenerator/MyEntity.default.fastshowgenerator.yml
     

3. First Use Case Generate a show action for an entity in a controller:

   use ACSEO\FastShowGeneratorBundle\Driver\AnnotationDriver;
   
   public function showAction(MyEntity $entity, EntityManagerInterface $em): Response
   {
       $fastShow = $this->container->get(AnnotationDriver::class);
       $fastShow->setEntity($entity);
       $fastShow->setGroup('default');
       $fastShow->setClassMetadata($em->getClassMetadata(get_class($entity)));
   
       $data = $fastShow->getShowableData();
       return $this->render('my_template.html.twig', ['data' => $data]);
   }
   

Implementation Patterns

Common Workflows

1. Dynamic Group Handling Use groups to manage different data views (e.g., admin, public):

   // In YAML
   groups: {admin, public}
   
   // In controller
   $fastShow->setGroup('admin'); // or 'public'
   

2. Twig Integration Pass generated data directly to Twig:

   {% for property, value in data %}
       <div>{{ property.label }}: {{ value }}</div>
   {% endfor %}
   

3. Service-Based Generation Extend the bundle by creating a service that wraps the driver:

   # config/services.yaml
   services:
       App\Service\ShowGenerator:
           arguments:
               $annotationDriver: '@acseo_fast_show_generator.driver.annotation'
               $yamlDriver: '@acseo_fast_show_generator.driver.yaml'
   

4. Event Listeners Hook into entity lifecycle events to auto-generate show data:

   $fastShow->setEntity($entity);
   $fastShow->setGroup('default');
   $showData = $fastShow->getShowableData();
   
   // Use $showData in prePersist/preUpdate listeners
   

5. Hybrid Configuration Combine annotations and YAML for flexibility:

   • Use annotations for entity-wide defaults.
   • Override specific properties in YAML.

Integration Tips

• Symfony Forms: Use generated labels in form themes:

  {{ form_label(form.field, data[field.name].label) }}
  

• API Platform: Extend getOperationArgs to inject show data:

  public function getOperationArgs(Operation $operation, array $uriVariables, array $context = [])
  {
      $showData = $this->showGenerator->generate($operation->getClass(), 'default');
      return array_merge($context, ['show_data' => $showData]);
  }
  

• Doctrine Lifecycle Callbacks: Generate show data in postLoad:

  public function postLoad(LifecycleEventArgs $args): void
  {
      $entity = $args->getObject();
      $entity->setShowData($this->showGenerator->generate($entity, 'default'));
  }
  

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear cache after adding/updating YAML config:

     php bin/console cache:clear
     

   • Annotations require a cache rebuild:

     php bin/console doctrine:cache:clear-metadata
     

2. Group Mismatches

   • Ensure YAML/annotation groups match controller calls:

     // Throws exception if group doesn't exist
     $fastShow->setGroup('nonexistent');
     

   • Default to default group if unsure.

3. Circular References

   • Avoid bidirectional associations without show: false:

     # YAML
     user:
         show: false
     

   • Or use @ACSEOFastShowGenerator\Show(show=false).

4. EntityManager Dependency

   • Always pass ClassMetadata via $em->getClassMetadata():

     $fastShow->setClassMetadata($em->getClassMetadata(get_class($entity)));
     

5. Namespace Conflicts

   • If using annotations, ensure the use statement is correct:

     // Wrong (throws error)
     use ACSEO\FastShowGeneratorBundle\Annotations as Show;
     
     // Correct
     use ACSEO\FastShowGeneratorBundle\Annotations\Show;
     

Debugging

1. Validate YAML Syntax Use Symfony’s validator:

   php bin/console debug:config acseo_fast_show_generator
   

   Check for missing files or invalid YAML.

2. Annotation Errors Enable annotation debugging:

   $fastShow->setDebug(true); // Logs missing annotations
   

3. Data Dumping Dump raw show data for inspection:

   $data = $fastShow->getShowableData();
   dump($data); // Check structure in CLI
   

Extension Points

1. Custom Drivers Implement ACSEO\FastShowGeneratorBundle\Driver\DriverInterface:

   class CustomDriver implements DriverInterface
   {
       public function getShowableData(): array
       {
           // Custom logic (e.g., database queries)
           return [];
       }
   }
   

   Register in services.yaml:

   services:
       App\Driver\CustomDriver:
           tags: ['acseo_fast_show_generator.driver']
   

2. Override Default Labels Use a compiler pass to modify labels dynamically:

   public function process(ContainerBuilder $container)
   {
       $definition = $container->findDefinition('acseo_fast_show_generator.driver.annotation');
       $definition->addMethodCall('setLabelOverride', ['property' => 'customLabel']);
   }
   

3. Add Custom Properties Extend the Show annotation:

   /**
    * @Annotation
    * @Target({"PROPERTY"})
    */
   class Show extends \Doctrine\Common\Annotations\Annotation
   {
       public $label;
       public $show;
       public $groups;
       public $customProperty; // Add new field
   }
   

   Update the driver to handle the new property.

4. Event Dispatching Dispatch events before/after data generation:

   $dispatcher->dispatch(new ShowDataEvent($entity, $data), 'fast_show_generator.generate');