Bootstrap Datetimepicker Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install via CDN (Recommended for quick use) Add to your resources/views/layouts/app.blade.php (or equivalent):

   <!-- CSS -->
   <link href="https://cdnjs.cloudflare.com/ajax/libs/eonasdan-bootstrap-datetimepicker/5.0.0/css/bootstrap-datetimepicker.min.css" rel="stylesheet">
   
   <!-- JS (after jQuery and Bootstrap) -->
   <script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.29.1/moment.min.js"></script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/eonasdan-bootstrap-datetimepicker/5.0.0/js/bootstrap-datetimepicker.min.js"></script>
   

2. Basic Initialization In your Blade template:

   <input type="text" class="form-control datetimepicker" id="example-datetimepicker">
   <script>
       $(function() {
           $('#example-datetimepicker').datetimepicker();
       });
   </script>
   

3. First Use Case: Form Input Use with Laravel Form Requests:

   // app/Http/Requests/StoreEventRequest.php
   public function rules() {
       return [
           'event_date' => 'required|date_format:Y-m-d H:i',
       ];
   }
   

   Bind to a model:

   $event->event_date = $request->input('event_date');
   

Implementation Patterns

Common Workflows

1. Dynamic Initialization Use Laravel Blade directives to conditionally initialize:

   @if($showDatepicker)
       <script>
           $(function() {
               $('#datetimepicker').datetimepicker({
                   useCurrent: false,
                   format: 'YYYY-MM-DD HH:mm'
               });
           });
       </script>
   @endif
   

2. Integration with Livewire/Alpine Livewire Example:

   // app/Http/Livewire/EventForm.php
   public function mount() {
       $this->event_date = now()->format('Y-m-d H:i');
   }
   
   public function render() {
       return view('livewire.event-form');
   }
   

   <!-- resources/views/livewire/event-form.blade.php -->
   <input type="text" wire:model="event_date" id="datetimepicker">
   <script>
       document.addEventListener('livewire:init', () => {
           $('#datetimepicker').datetimepicker();
       });
   </script>
   

3. Reusable Component Create a Blade component:

   php artisan make:component DateTimePicker
   

   <!-- resources/views/components/date-time-picker.blade.php -->
   <input type="text" class="form-control" id="datetimepicker-{{ $id }}"
          wire:model="{{ $model ?? null }}" {{ $attributes }}>
   <script>
       $(function() {
           $('#datetimepicker-{{ $id }}').datetimepicker({
               @if($options)
                   {{ json_encode($options) }}
               @endif
           });
       });
   </script>
   

4. Validation Feedback Combine with Laravel validation messages:

   <x-date-time-picker wire:model="event_date" id="event-date" />
   @error('event_date')
       <div class="text-danger">{{ $message }}</div>
   @enderror
   

Integration Tips

• Localization: Use moment.js locales for non-English dates:

  <script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.29.1/locale/fr.js"></script>
  <script>
      $(function() {
          $('#datetimepicker').datetimepicker({
              locale: 'fr'
          });
      });
  </script>
  

• Server-Side Timezones: Convert user input to UTC in your model:

  // app/Models/Event.php
  protected $casts = [
      'event_date' => 'datetime',
  ];
  
  // Automatically converts to UTC on save
  

• AJAX Forms: Ensure datetimepicker updates hidden inputs:

  <input type="text" id="datetimepicker" class="form-control">
  <input type="hidden" name="event_date" id="event_date_hidden">
  <script>
      $('#datetimepicker').on('dp.change', function(e) {
          $('#event_date_hidden').val(e.date.format('YYYY-MM-DD HH:mm'));
      });
  </script>
  

Gotchas and Tips

Pitfalls

1. jQuery Dependency

   • Issue: Forgetting to include jQuery before the datetimepicker script.
   • Fix: Ensure order in your layout:

     <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
     <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js"></script>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/eonasdan-bootstrap-datetimepicker/5.0.0/js/bootstrap-datetimepicker.min.js"></script>
     

2. Timezone Mismatches

   • Issue: User selects 2023-12-31 23:00 in their local timezone, but the server stores it as UTC 2024-01-01 04:00.
   • Fix: Use Carbon to handle conversions:

     $userInput = '2023-12-31 23:00';
     $eventDate = Carbon\Carbon::parse($userInput)->timezone('UTC');
     

3. Mobile Compatibility

   • Issue: Touch events may not work as expected on mobile devices.
   • Fix: Add touchstart event listeners or use a mobile-friendly alternative like Pikaday.

4. Conflicting Selectors

   • Issue: Multiple datetimepickers with the same ID or class.
   • Fix: Use unique IDs or data attributes:

     <input type="text" data-datetimepicker="event-date" class="datetimepicker">
     

     $('[data-datetimepicker]').datetimepicker();
     

5. Deprecated Methods

   • Issue: Using old syntax (e.g., $.fn.datetimepicker.defaults).
   • Fix: Use the modern config object:

     // Old (deprecated)
     $.fn.datetimepicker.defaults.timeFormat = 'HH:mm';
     
     // New
     $('#datetimepicker').datetimepicker({
         timepicker: true,
         format: 'YYYY-MM-DD HH:mm'
     });
     

Debugging Tips

1. Check Console for Errors

   • Open browser dev tools (F12) and look for Uncaught TypeError or Cannot read property 'datetimepicker' of undefined.

2. Verify Initialization Timing

   • Ensure the datetimepicker script runs after the DOM is loaded:

     $(document).ready(function() {
         // Initialize here
     });
     

3. Inspect Hidden Inputs

   • Use console.log() to verify the hidden input value matches the displayed date:

     $('#datetimepicker').on('dp.change', function(e) {
         console.log('Selected date:', e.date.format());
         console.log('Hidden input:', $('#event_date_hidden').val());
     });
     

4. Disable for Testing

   • Temporarily disable the datetimepicker to isolate issues:

     // In your initialization
     $('#datetimepicker').data('DateTimePicker').destroy();
     

Extension Points

1. Custom Formatting

   • Override the default format globally:

     $.fn.datetimepicker.dates['en'].format = 'DD/MM/YYYY HH:mm';
     

2. Event Listeners

   • Attach custom logic to datetimepicker events:

     $('#datetimepicker').on('dp.show', function() {
         console.log('Picker shown');
     }).on('dp.hide', function() {
         console.log('Picker hidden');
     });
     

3. Dynamic Updates

   • Reinitialize datetimepicker after AJAX calls:

     $.ajax({
         url: '/update-date',
         success: function() {
             $('#datetimepicker').data('DateTimePicker').update();
         }
     });
     

4. Theming

   • Customize the picker’s appearance via CSS:

     .datetimepicker {
         z-index: 9999 !important;
     }
     .datetimepicker table tr td.active {
         background-color: #3498db !important;
     }
     

Configuration Quirks

1. useCurrent vs defaultDate

   • useCurrent: true sets the current date/time on initialization.
   • defaultDate allows setting a specific default (e.g., new Date(2023, 0, 1)).

2. sideBySide vs widgetPositioning

   • sideBySide: true places date/time pickers side-by-side (deprecated in v5).
   • Use widgetPositioning: { horizontal: 'auto' } for modern