Bootstrap Datepicker Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install via npm (assuming Bootstrap 5+ is already in your project):

   npm install @eternicode/bootstrap-datepicker
   

   Add to your resources/js/app.js (or equivalent):

   import 'bootstrap-datepicker';
   

2. Include CSS/JS in Blade:

   <!-- resources/views/your-form.blade.php -->
   <link href="{{ asset('css/bootstrap-datepicker.min.css') }}" rel="stylesheet">
   <script src="{{ asset('js/bootstrap-datepicker.min.js') }}"></script>
   

3. Basic Initialization:

   <input type="text" class="form-control datepicker" name="event_date">
   <script>
       $(document).ready(function() {
           $('.datepicker').datepicker();
       });
   </script>
   

First Use Case: Form Validation

Use the datepicker class on an <input> field to instantly enable date selection. Pair with Laravel Validation:

$request->validate([
    'event_date' => 'required|date_format:Y-m-d',
]);

Implementation Patterns

Common Workflows

1. Dynamic Initialization (Laravel Blade + Alpine.js):

   <input x-data="{ date: '' }" x-model="date" class="datepicker" name="due_date">
   <script>
       document.addEventListener('alpine:init', () => {
           Alpine.data('datepicker', () => ({
               init() {
                   this.$nextTick(() => {
                       $(this.$el).datepicker({
                           format: 'yyyy-mm-dd',
                           autoclose: true
                       });
                   });
               }
           }));
       });
   </script>
   

2. Server-Side Integration:

   • Store: Save dates as Carbon instances in your database.
   • Retrieve: Pass formatted dates to the view:

     return view('form', ['default_date' => $event->date->format('d/m/Y')]);
     

   • Update: Use Carbon::parse($request->date) to handle input.

3. Multi-Date Picker (Range Selection):

   <div class="input-group">
       <input type="text" class="form-control datepicker" name="start_date">
       <span class="input-group-text">to</span>
       <input type="text" class="form-control datepicker" name="end_date">
   </div>
   <script>
       $('.datepicker').datepicker({
           autoclose: true,
           todayHighlight: true,
           toggleActive: true // Enable range selection
       });
   </script>
   

Laravel-Specific Tips

• Form Requests: Extend FormRequest to handle date parsing:

  public function rules()
  {
      return [
          'date' => 'required|date_format:d/m/Y',
      ];
  }
  
  public function prepareForValidation()
  {
      $this->merge([
          'date' => Carbon::createFromFormat('d/m/Y', $this->date)->format('Y-m-d'),
      ]);
  }
  

• Livewire/Alpine: Use wire:ignore to prevent Livewire from touching the datepicker:

  <input wire:ignore class="datepicker" x-model="date">
  

Gotchas and Tips

Pitfalls

1. jQuery Dependency:

   • The package requires jQuery. Ensure it’s loaded before bootstrap-datepicker.js.
   • Fix: Add to resources/js/app.js:

     import 'jquery';
     import 'bootstrap-datepicker';
     

2. Date Format Mismatches:

   • If format isn’t set, the package defaults to mm/dd/yyyy. Always explicitly define it:

     $('.datepicker').datepicker({ format: 'yyyy-mm-dd' });
     

3. Conflicts with Bootstrap 5:

   • Bootstrap 5 uses data-bs-* attributes. Avoid naming conflicts:

     <!-- Bad: Overrides Bootstrap 5 tooltip -->
     <input data-toggle="tooltip" class="datepicker">
     
     <!-- Good -->
     <input data-bp-toggle="tooltip" class="datepicker">
     

4. Server-Side Timezone Issues:

   • Store dates in UTC in the database, but display in the user’s timezone:

     // Store
     $event->date = $request->date; // Assumes Y-m-d format
     
     // Display
     $event->date->setTimezone($user->timezone)->format('d/m/Y');
     

Debugging

• Console Errors: Check for missing jQuery or incorrect initialization order.
• Event Listeners: Use onShow, onSelect, etc., for debugging:

  $('.datepicker').datepicker({
      onShow: function() { console.log('Picker shown'); },
      onSelect: function(date) { console.log('Selected:', date); }
  });
  

Extension Points

1. Custom Templates: Override the default HTML template via template option:

   $('.datepicker').datepicker({
       template: `
           <div class="custom-datepicker">
               <div class="custom-header"></div>
               <div class="custom-body"></div>
           </div>
       `
   });
   

2. Localization: Load translations dynamically:

   $('.datepicker').datepicker({
       language: '{{ app()->getLocale() }}',
       weekStart: 1 // For ISO week numbering
   });
   

   Ensure locale files exist in node_modules/bootstrap-datepicker/locales/.

3. Accessibility: Add ARIA attributes for screen readers:

   $('.datepicker').datepicker({
       autoclose: true,
       todayBtn: 'linked',
       keyboardNavigation: true,
       todayHighlight: true
   });
   

   Pair with Blade:

   <input aria-label="Select event date" class="datepicker">
   

4. Laravel Mix/Webpack: For better asset handling, configure webpack.mix.js:

   mix.js('resources/js/app.js', 'public/js')
      .postCss('resources/css/app.css', 'public/css', []);