Component Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ascensodigital/component-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       AscensoDigital\ComponentBundle\AscensoDigitalComponentBundle::class => ['all' => true],
   ];
   

2. First Use Case: Form Extensions Enable the Twig form extensions in your template:

   {% form_theme form '_ADComponentBundle:Form:fields.html.twig' %}
   

   This provides pre-built field templates (e.g., text, textarea, select) with enhanced styling/validation.

3. Doctrine Extensions Check src/Resources/config/doctrine/orm/ADComponentBundle.orm.xml for custom Doctrine behaviors (e.g., soft deletes, timestamps). Enable via:

   # config/packages/doctrine.yaml
   orm:
       mappings:
           ADComponentBundle: ~
   

Implementation Patterns

Form Workflows

1. Custom Field Types Extend existing fields (e.g., ADTextFieldType) by overriding templates in templates/ADComponentBundle/Form/:

   {# templates/ADComponentBundle/Form/text_field.html.twig #}
   {% extends '_ADComponentBundle:Form:text_field.html.twig' %}
   {% block label %}{{ label }}<span class="required">*</span>{% endblock %}
   

2. Validation Integration Use the bundle’s validators (e.g., ADUniqueEntityValidator) in your entities:

   use AscensoDigital\ComponentBundle\Validator\Constraints\UniqueEntity;
   
   /**
    * @UniqueEntity("email")
    */
   private $email;
   

3. Dynamic Forms Leverage Twig’s ad_component_form function for dynamic rendering:

   {{ ad_component_form(form, {
       'field_types': {
           'email': 'ADTextFieldType',
           'password': 'ADPasswordFieldType'
       }
   }) }}
   

Doctrine Patterns

1. Lifecycle Callbacks Use the bundle’s ADLifecycleCallbacks trait for common logic (e.g., createdAt, updatedAt):

   use AscensoDigital\ComponentBundle\Doctrine\ADLifecycleCallbacks;
   
   class User implements ADLifecycleCallbacks {
       use ADLifecycleCallbacks;
       // ...
   }
   

2. Query Extensions Add custom DQL functions via ADQueryListener:

   # config/packages/doctrine.yaml
   doctrine:
       dql:
           string_functions:
               AD_CONTAINS: AscensoDigital\ComponentBundle\Doctrine\DQL\ADContainsFunction
   

Twig Extensions

1. Custom Filters Register new Twig filters in services.yaml:

   services:
       app.twig.ad_extension:
           class: App\Twig\ADCustomExtension
           tags: ['twig.extension']
   

2. Component-Based Layouts Use ad_component to embed reusable blocks:

   {{ ad_component('user_card', { user: user }) }}
   

Gotchas and Tips

Debugging

1. Form Template Overrides

   • Issue: Custom templates aren’t loading.
   • Fix: Clear cache (php bin/console cache:clear) and verify the template path matches _ADComponentBundle:Form:fields.html.twig.

2. Doctrine Mappings

   • Issue: ADLifecycleCallbacks not triggering.
   • Fix: Ensure the entity is mapped in ADComponentBundle.orm.xml and the trait is used after Doctrine annotations.

3. Twig Extensions

   • Issue: ad_component_form throws "Undefined function" errors.
   • Fix: Register the Twig extension in config/packages/twig.yaml:

     twig:
         globals:
             ad_component: '@ascenso_digital_component.twig.extension'
     

Configuration Quirks

1. Symfony 5+ Compatibility

   • The bundle supports Symfony 5 but lacks explicit autoconfigure: true in services.yaml. Add this to avoid manual service registration:

     services:
         _defaults:
             autoconfigure: true
     

2. Validation Constraints

   • Tip: The UniqueEntity constraint requires a UniqueEntityValidator. Ensure it’s autowired:

     use AscensoDigital\ComponentBundle\Validator\UniqueEntityValidator;
     
     class YourValidator implements ConstraintValidator {
         public function __construct(private UniqueEntityValidator $validator) {}
     }
     

Extension Points

1. Custom Field Types

   • Extend ADAbstractFieldType to create reusable components:

     class ADDateRangeFieldType extends ADAbstractFieldType {
         public function getParent() { return 'ADTextFieldType'; }
         public function getBlockPrefix() { return 'ad_date_range'; }
     }
     

2. Doctrine Events

   • Subscribe to ADLifecycleEvents for pre/post operations:

     use AscensoDigital\ComponentBundle\Event\ADLifecycleEvent;
     
     class CustomLifecycleSubscriber implements EventSubscriber {
         public static function getSubscribedEvents() {
             return [
                 ADLifecycleEvent::PRE_PERSIST => 'onPrePersist',
             ];
         }
     }
     

3. Twig Components

   • Create modular components in templates/components/ and reference them via:

     {% include 'components/_ad_modal.html.twig' with {
         'title': 'Custom Title',
         'content': content
     } %}