Enquiry Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bodaclick/enquiry-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Bodaclick\EnquiryBundle\BDKEnquiryBundle::class => ['all' => true],
   ];
   

2. Publish Configuration

   php artisan vendor:publish --tag=bdkenquiry-config
   

   Review config/bdkenquiry.php for default settings (e.g., default_entity, validation_rules).

3. First Use Case: Basic Enquiry Form Define an entity (e.g., ContactRequest) with fields like name, email, message. Use the bundle’s EnquiryType form builder:

   use Bodaclick\EnquiryBundle\Form\Type\EnquiryType;
   
   $builder->add('contact', EnquiryType::class, [
       'entity' => ContactRequest::class,
       'validation_groups' => ['Default', 'contact'],
   ]);
   

Implementation Patterns

Core Workflows

1. Dynamic Form Handling

   • Use EnquiryType to auto-generate forms for any entity. Map fields via annotations or YAML:

     # config/bdkenquiry/entities/ContactRequest.yml
     fields:
         name: { label: "Full Name", required: true }
         email: { type: "email", required: true }
         message: { type: "textarea" }
     

2. Entity Integration

   • Extend base Enquiry entity or create custom ones (e.g., SupportTicket):

     use Bodaclick\EnquiryBundle\Entity\Enquiry;
     
     class SupportTicket extends Enquiry {
         // Custom fields/methods
     }
     

   • Register in config/bdkenquiry.php:

     'entities' => [
         'support_ticket' => SupportTicket::class,
     ],
     

3. Validation & Processing

   • Leverage Symfony’s validation component with custom groups:

     // In your controller
     $enquiry = $form->getData();
     $validator = $this->get('validator');
     $errors = $validator->validate($enquiry, ['contact', 'Default']);
     

   • Use events (enquiry.pre_save, enquiry.post_save) for custom logic:

     $dispatcher->addListener('enquiry.pre_save', function ($enquiry) {
         $enquiry->setStatus('pending');
     });
     

4. API/CLI Access

   • Submit enquiries via API:

     curl -X POST /api/enquiries \
          -d '{"entity":"contact","data":{"name":"John"}}'
     

   • Use EnquiryManager service:

     $manager = $this->get('bdkenquiry.manager');
     $enquiry = $manager->create('contact', $data);
     $manager->save($enquiry);
     

Gotchas and Tips

Pitfalls

1. Entity Mapping Issues

   • Problem: Fields in your entity don’t match the form.
   • Fix: Ensure fields are defined in YAML/annotations or use MappingBuilder:

     $builder->mapEntityFields(ContactRequest::class);
     

2. Validation Overrides

   • Problem: Custom validation groups aren’t applied.
   • Fix: Explicitly pass groups to EnquiryType:

     'validation_groups' => ['Default', 'contact', 'custom_group']
     

3. Event Dispatching

   • Problem: Events fire too early/late.
   • Fix: Check event priorities in config/bdkenquiry.php:

     'events' => [
         'enquiry.pre_save' => 10, // Lower = earlier
     ],
     

4. Archived Status

   • Risk: No active maintenance.
   • Mitigation: Fork the repo or patch critical issues locally.

Debugging Tips

• Log Enquiry Data:

  $dispatcher->addListener('enquiry.pre_save', function ($enquiry) {
      \Log::debug('Enquiry data:', $enquiry->toArray());
  });
  

• Validate YAML: Use Symfony’s yaml component to validate config:

  php bin/console debug:config bdkenquiry
  

Extension Points

1. Custom Field Types Override EnquiryType to add new field types:

   class CustomEnquiryType extends EnquiryType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('custom_field', CustomFieldType::class);
       }
   }
   

2. Database Drivers Extend EnquiryStorage to support non-DOCTRINE DBAL:

   class CustomStorage extends EnquiryStorage {
       public function save(Enquiry $enquiry) {
           // Custom logic
       }
   }
   

3. Email Notifications Subscribe to enquiry.post_save and send emails:

   $dispatcher->addListener('enquiry.post_save', function ($enquiry) {
       $this->get('mailer')->send(new EnquiryEmail($enquiry));
   });
   

Configuration Quirks

• Default Entity: Set in config/bdkenquiry.php to avoid hardcoding:

  'default_entity' => 'App\Entity\ContactRequest',
  

• Field Types: Use FQCNs for custom types:

  fields:
      terms_accepted: { type: "checkbox", required: true }