Laravel Hours Helper Laravel Package

Getting Started

Install via Composer:

composer require label84/laravel-hours-helper

First Use Case: Generate a time dropdown for appointment scheduling.

use Label84\HoursHelper\Facades\HoursHelper;

// Basic 30-minute intervals between 8 AM and 9:30 AM
$slots = HoursHelper::create('08:00', '09:30', 30);

// Pass to Blade for a dropdown
return view('appointments.create', ['slots' => $slots]);

Key Files to Review:

• vendor/label84/laravel-hours-helper/src/Facades/HoursHelper.php (API reference)
• tests/HoursHelperTest.php (edge cases and examples)

Implementation Patterns

Core Workflow

1. Generate Slots:

   $slots = HoursHelper::create(
       start: '09:00',
       end: '17:00',
       interval: 60, // minutes
       format: 'g:i A',
       exclusions: [['12:00', '13:00']] // lunch break
   );
   

2. Blade Integration:

   <select name="appointment_time">
       @foreach($slots as $slot)
           <option>{{ $slot }}</option>
       @endforeach
   </select>
   

3. API Response:

   return response()->json(['slots' => $slots]);
   

Advanced Patterns

Dynamic Exclusions from Database

$excludedRanges = DB::table('blocked_slots')
    ->where('user_id', auth()->id())
    ->pluck('range');

$slots = HoursHelper::create('08:00', '18:00', 30, 'H:i', $excludedRanges);

Multi-Day Scheduling

// Generate slots for a 3-day event
$slots = HoursHelper::create(
    '2024-06-01 09:00',
    '2024-06-03 17:00',
    60,
    'Y-m-d g:i A'
);

Livewire Integration

public function mount() {
    $this->slots = HoursHelper::create('08:00', '18:00', 30);
}

public function updateExclusions($exclusions) {
    $this->slots = HoursHelper::create('08:00', '18:00', 30, 'H:i', $exclusions);
}

Background Job Processing

// Dispatch a job for each slot
foreach (HoursHelper::create('09:00', '17:00', 60) as $slot) {
    SendReminderJob::dispatch($slot);
}

Custom Formatting with Carbon

$slots = HoursHelper::create('08:00', '18:00', 30)
    ->map(fn ($time) => Carbon::parse($time)->format('h \o\'clock'));

Gotchas and Tips

Common Pitfalls

1. Timezone Assumptions:

   • Uses Laravel’s default timezone. For multi-timezone apps, explicitly set:

     $slots = HoursHelper::create('08:00', '18:00', 30, 'H:i', [], 'America/New_York');
     

2. Exclusion Overlaps:

   • Exclusions are processed as-is. Overlapping ranges (e.g., [09:00,10:00] and [09:30,10:30]) may produce unexpected gaps. Normalize exclusions first:

     $normalizedExclusions = array_merge(...$exclusions);
     

3. Past-Midnight Edge Cases:

   • Works correctly but test thoroughly with ranges crossing midnight:

     $slots = HoursHelper::create('23:00', '01:00', 60); // Includes '00:00'
     

4. Large Ranges:

   • Generating monthly/yearly slots may hit memory limits. Use chunking:

     $slots->chunk(1000); // Process in batches
     

5. Invalid Inputs:

   • No built-in validation. Sanitize inputs:

     $start = Carbon::parse($request->start)->format('H:i');
     

Debugging Tips

1. Verify Output:

   dd($slots->all()); // Inspect raw values
   

2. Check Exclusions:

   $slots->filter(fn ($time) => !collect($exclusions)->contains(fn ($range) => ...));
   

3. Performance Profiling:

   • Use Laravel Debugbar to monitor memory/CPU for large ranges.

Extension Points

1. Custom Interval Logic:

   • Override the service provider to add non-linear intervals:

     // app/Providers/HoursHelperServiceProvider.php
     public function register() {
         $this->app->extend('hours-helper', function ($helper) {
             $helper->addCustomInterval('custom', function ($start, $end, $step) {
                 // Implement logic
             });
             return $helper;
         });
     }
     

2. Database Backed Exclusions:

   HoursHelper::macro('withDatabaseExclusions', function ($query) {
       $exclusions = $query->get()->pluck('range');
       return $this->create($this->start, $this->end, $this->interval, $this->format, $exclusions);
   });
   

3. Timezone-Aware Helper:

   HoursHelper::macro('inTimezone', function ($timezone) {
       return $this->setTimezone($timezone);
   });
   

Configuration Quirks

1. Facade vs. Class:

   • Prefer the facade for Blade/Livewire, but use the class for testing:

     // Facade (Blade)
     @php
         $slots = \Label84\HoursHelper\Facades\HoursHelper::create(...);
     @endphp
     
     // Class (Tests)
     $helper = new \Label84\HoursHelper\HoursHelper();
     $slots = $helper->create(...);
     

2. Format Overrides:

   • The format parameter uses PHP’s DateTime::format(). Test with:

     $slots = HoursHelper::create('08:00', '18:00', 30, 'g:i A'); // '8:00 AM'
     

3. Interval Units:

   • Interval is in minutes, not seconds or hours. Common values:
     • 15 (15-minute slots)
     • 30 (30-minute slots)
     • 60 (hourly slots)