Datetimepicker Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexvasilyev/datetimepicker-bundle
   

   Enable the bundle in config/bundles.php (Symfony 4+):

   SC\DatetimepickerBundle\SCDatetimepickerBundle::class => ['all' => true],
   

   Run asset installation:

   php bin/console assets:install public/
   

2. Basic Usage: Add the DatetimeType to your form builder:

   use SC\DatetimepickerBundle\Form\Type\DatetimeType;
   
   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       $builder->add('eventDate', DatetimeType::class);
   }
   

3. Twig Integration: Include the form assets in your template:

   {% block stylesheets %}
       {{ form_stylesheet(form) }}
   {% endblock %}
   
   {% block javascripts %}
       {{ form_javascript(form) }}
   {% endblock %}
   

Implementation Patterns

Form Integration

• Default Behavior: Use DatetimeType as a drop-in replacement for Symfony’s DateTimeType or DateType.
• Customization: Pass pickerOptions to configure the datetime picker:

  $builder->add('customDate', DatetimeType::class, [
      'pickerOptions' => [
          'format' => 'YYYY-MM-DD HH:mm',
          'useCurrent' => true,
      ],
  ]);
  

Asset Management

• Separation of Concerns: Use form_stylesheet() and form_javascript() to auto-generate <link> and <script> tags for the datetime picker.
• Manual Inclusion: If needed, manually include dependencies (e.g., jQuery, Bootstrap) before the bundle’s JS:

  <script src="{{ asset('js/jquery.min.js') }}"></script>
  <script src="{{ asset('js/bootstrap.min.js') }}"></script>
  {{ form_javascript(form) }}
  

Validation and Data Binding

• Symfony Validation: The bundle respects Symfony’s validation constraints (e.g., @Assert\DateTime).
• Data Transformation: Ensure the format in pickerOptions matches Symfony’s expected format (e.g., YYYY-MM-DD for database storage).

Common Use Cases

1. Event Registration:

   $builder->add('startTime', DatetimeType::class, [
       'pickerOptions' => [
           'minView' => 'hour',
           'maxView' => 'decade',
       ],
   ]);
   

2. Appointment Scheduling:

   $builder->add('appointment', DatetimeType::class, [
       'pickerOptions' => [
           'startDate' => (new \DateTime())->format('m/d/Y'),
           'endDate' => (new \DateTime('+1 month'))->format('m/d/Y'),
       ],
   ]);
   

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • Ensure assets:install is run after updating dependencies.
   • For Symfony 4+, use public/ as the target directory (not web/).

2. Date Format Mismatch:

   • The format in pickerOptions must align with Symfony’s expected format. For example:
     • Picker: YYYY-MM-DD HH:mm
     • Symfony: Use DateTimeType with widget: single_text and format: 'Y-m-d H:i'.

3. Locale Inconsistencies:

   • Month/day names may differ between PHP (Intl) and JavaScript (Bootstrap). Override locales in js/locales/ if needed (as noted in the README).

4. Dependency Conflicts:

   • Ensure jQuery and Bootstrap are loaded before the datetime picker’s JS. Use Twig’s parent() to include base assets:

     {% block javascripts %}
         {{ parent() }}
         {{ form_javascript(form) }}
     {% endblock %}
     

Debugging

• Console Errors: Check browser console for missing assets or JS errors (e.g., $ is not defined → jQuery not loaded).
• Form Rendering: Use {{ dump(form.vars) }} in Twig to inspect form variables and options.

Extension Points

1. Custom Templates: Override the form theme (e.g., templates/form/div_datetime_widget.html.twig) to modify the HTML structure.

2. Dynamic Options: Pass dynamic options via form events:

   $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $form = $event->getForm();
       $data = $event->getData();
       $form->add('dynamicDate', DatetimeType::class, [
           'pickerOptions' => ['startDate' => $data->getMinDate()],
       ]);
   });
   

3. Localization: Extend the bundle’s locale files (e.g., Resources/public/js/locales/bootstrap-datetimepicker.fr.js) for custom translations.

Performance Tips

• Lazy Loading: Load the datetime picker JS only on pages where the form appears (e.g., via data-toggle or conditional Twig blocks).
• Cache Assets: Enable Symfony’s asset cache for production:

  # config/packages/twig.yaml
  twig:
      cache: '%kernel.cache_dir%/twig'