Light Field Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Run composer require corvet/light-field-bundle in your Symfony 8.4+ project. Ensure your composer.json meets the PHP 8.4+ and Symfony 8.0+ requirements.

2. Register Asset Dependencies Add Flatpickr and Inputmask to your config/packages/framework/importmap.php:

   return [
       'flatpickr' => 'https://cdn.jsdelivr.net/npm/flatpickr@latest/dist/flatpickr.min.js',
       'inputmask' => 'https://cdn.jsdelivr.net/npm/inputmask@latest/dist/inputmask.min.js',
   ];
   

   Then run:

   php bin/console importmap:require flatpickr inputmask
   

3. First Use Case Replace a standard DateType in your form with MaskedDateType:

   use Corvet\LightFieldBundle\Form\MaskedDateType;
   
   $builder->add('expiryDate', MaskedDateType::class, [
       'label' => 'Expiry Date (DD.MM.YYYY)',
       'widget' => 'single_text', // Default; omit for calendar-only
   ]);
   

   Twig Template:

   {{ form_row(form.expiryDate) }}
   

   The field will auto-format input as DD.MM.YYYY and render a dark-themed Flatpickr calendar.

Implementation Patterns

Workflows

1. Form Integration

   • Default Behavior: Combines masked input (for manual entry) + calendar (for selection).
   • Calendar-Only Mode: Omit the widget option to disable the text input:

     $builder->add('birthDate', MaskedDateType::class, ['widget' => 'calendar']);
     

   • Custom Placeholders: Pass via attr:

     $builder->add('dueDate', MaskedDateType::class, [
         'attr' => ['placeholder' => 'DD/MM/YYYY (US format)'],
     ]);
     

2. Asset Optimization

   • Lazy Loading: AssetMapper handles JS/CSS on-demand. No manual webpack or npm needed.
   • Custom Themes: Override Flatpickr’s dark theme by extending its CSS in your assets:

     /* assets/app.css */
     .flatpickr-dark .flatpickr-calendar {
         background: #1a1a1a !important;
     }
     

3. Validation Integration

   • Leverage Symfony’s built-in DateType validation (e.g., constraints: [NotBlank(), GreaterThan('today')]).
   • The mask ensures client-side UX matches server-side validation (e.g., dd.mm.yyyy format).

4. Dynamic Forms

   • Use MaskedDateType in dynamic form builders (e.g., with FormFactory or EntityType for collections):

     $formFactory->createNamedBuilder('order', null, null)
         ->add('shipDate', MaskedDateType::class, ['required' => false]);
     

Pro Tips

• Localization: The mask adapts to locale settings (e.g., fr_FR → JJ.MM.AAAA). Override via:

  $builder->add('date', MaskedDateType::class, [
      'mask_locale' => 'de_DE', // German format: TT.MM.JJJJ
  ]);
  

• Accessibility: The bundle includes ARIA labels by default. Extend with custom attr:

  $builder->add('deadline', MaskedDateType::class, [
      'attr' => ['aria-describedby' => 'deadline-help'],
  ]);
  

Gotchas and Tips

Pitfalls

1. Asset Loading Failures

   • Symptom: Calendar/input mask doesn’t render.
   • Cause: Missing importmap:require or incorrect CDN paths.
   • Fix:
     • Verify importmap:require was run post-install.
     • Check browser console for 404s on flatpickr.min.js/inputmask.min.js.
     • Use local assets (e.g., node_modules) if CDN fails:

       return [
           'flatpickr' => '/node_modules/flatpickr/dist/flatpickr.min.js',
       ];
       

2. Mask Conflicts

   • Symptom: Input mask strips data when using "Today" or "Clear" buttons.
   • Cause: Custom JavaScript interfering with Flatpickr’s event handlers.
   • Fix: Ensure no global $() or jQuery overrides Flatpickr’s selectors. Use:

     // assets/app.js
     document.addEventListener('DOMContentLoaded', () => {
         // Your custom JS here (avoid document.ready conflicts)
     });
     

3. PHP 8.4+ Strict Typing

   • Symptom: TypeError in MaskedDateType constructor.
   • Cause: Bundle assumes PHP 8.4’s typed properties. Downgrade or patch:

     // Override the type in your custom form class
     public function __construct(string $class = null, array $options = [])
     {
         parent::__construct($class, $options);
     }
     

4. Symfony 8.4+ AssetMapper Quirks

   • Symptom: Styles not applied despite correct imports.
   • Fix: Explicitly include Flatpickr’s CSS in importmap.php:

     return [
         'flatpickr' => [
             'js' => 'https://cdn.jsdelivr.net/npm/flatpickr@latest',
             'css' => 'https://cdn.jsdelivr.net/npm/flatpickr@latest/dist/flatpickr.min.css',
         ],
     ];
     

Debugging

• Console Logs: Check for Uncaught ReferenceError in browser dev tools (missing assets).
• Network Tab: Verify flatpickr.min.js and inputmask.min.js load with 200 OK.
• Symfony Debug: Enable debug: true in config/packages/dev/debug.php to log form type errors.

Extension Points

1. Custom Buttons Extend Flatpickr’s footer via Twig:

   {% block corvet_light_field_buttons %}
       <button type="button" class="flatpickr-button" data-fp-action="customAction">
           Custom Action
       </button>
   {% endblock %}
   

   Register the block in your base template.

2. Dynamic Masking Override the mask format via JavaScript:

   document.addEventListener('DOMContentLoaded', () => {
       document.querySelectorAll('.masked-date-input').forEach(el => {
           el._inputmask.options.mask = 'MM-DD-YYYY'; // US format
       });
   });
   

3. Server-Side Format Handling Ensure your entity setter/getter aligns with the mask format:

   // src/Entity/Order.php
   public function setCreatedAt(?\DateTimeInterface $createdAt): self
   {
       $this->createdAt = $createdAt?->format('Y-m-d'); // Store as YYYY-MM-DD
       return $this;
   }
   

4. Testing Use Symfony’s FormTestCase to validate masked input:

   public function testMaskedDateSubmission()
   {
       $form = $this->factory->create(MaskedDateType::class);
       $form->submit('15.12.2023'); // DD.MM.YYYY
       $this->assertEquals('2023-12-15', $form->getData()->format('Y-m-d'));
   }