Zap Laravel Package

Getting Started

1. Installation:

   composer require laraveljutsu/zap
   php artisan vendor:publish --provider="Zap\ZapServiceProvider"
   php artisan migrate
   

2. Make a model schedulable:

   use Zap\Models\Concerns\HasSchedules;
   
   class Doctor extends Model
   {
       use HasSchedules;
   }
   

3. First use case: Define working hours for a doctor

   use Zap\Facades\Zap;
   
   Zap::for($doctor)
       ->named('Office Hours')
       ->availability()
       ->forYear(2025)
       ->addPeriod('09:00', '12:00')
       ->addPeriod('14:00', '17:00')
       ->weekly(['monday', 'tuesday', 'wednesday', 'thursday', 'friday'])
       ->save();
   

4. Check availability:

   $slots = $doctor->getBookableSlots('2025-01-15', 60, 15);
   

Implementation Patterns

Core Workflows

1. Define Schedules:

   • Use Zap::for($model)->named('Schedule Name')->[type]() where [type] is availability(), appointment(), blocked(), or custom().
   • Chain recurrence methods like weekly(), monthly(), everyThreeWeeks(), etc.
   • Add time periods with addPeriod('start', 'end').

2. Recurring Patterns:

   • Daily/Weekly: Use daily(), weekly(['monday', 'friday']).
   • Monthly: Use monthly(['days_of_month' => [1, 15]]) or ordinal methods like firstWednesdayOfMonth().
   • Custom Intervals: Use everyThreeWeeks(), everyFourMonths().

3. Querying:

   • Bookable Slots: $model->getBookableSlots('2025-01-15', 60, 15).
   • Next Slot: $model->getNextBookableSlot('2025-01-15', 60, 15).
   • Conflicts: Zap::findConflicts($schedule).

4. Metadata:

   • Attach metadata to schedules with withMetadata(['key' => 'value']) for custom data storage.

Integration Tips

1. Validation Rules:

   • Use noOverlap(), allowOverlap(), maxDuration(120), workingHoursOnly('09:00', '17:00') for custom validation.

2. Frontend Integration:

   • Use getBookableSlots() to fetch available time slots for a date range and display them in a calendar UI.
   • Use isBookableAtTime() to validate user selections in real-time.

3. Event Triggers:

   • Listen for Zap\Events\ScheduleCreated, Zap\Events\ScheduleUpdated, and Zap\Events\ScheduleDeleted to trigger notifications or sync external systems.

4. Testing:

   • Use Zap::fake() to mock schedules in unit tests.
   • Verify availability checks with assertTrue($model->isBookableAtTime(...)).

Common Use Cases

1. Appointment Booking:

   • Define availability for a doctor, block lunch hours, and create appointments with metadata like patient IDs.

2. Resource Management:

   • Schedule meeting rooms with availability periods and block them for specific appointments.

3. Employee Shifts:

   • Define regular shifts for employees and block vacation periods.

Gotchas and Tips

Pitfalls

1. Timezone Handling:

   • Ensure timezone consistency in your application. Zap normalizes timezones internally, but mismatches can cause unexpected week boundaries.

2. UUID/ULID Support:

   • If using non-integer primary keys, configure custom models and migrations before running migrations. Forgetting this can cause foreign key errors.

3. Overlapping Schedules:

   • By default, noOverlap() is enabled. If you need overlapping schedules, explicitly use allowOverlap().

4. Date Range Conflicts:

   • When using from() and to(), ensure the range is inclusive and correctly handles timezone transitions.

5. Recurrence Edge Cases:

   • Test schedules around month-end, daylight saving time changes, and leap years to catch edge cases.

Debugging

1. Querying Schedules:

   • Use dd($model->schedulesForDate('2025-01-15')->get()) to inspect all schedules for a date.

2. Conflict Detection:

   • Use Zap::findConflicts($schedule) to debug overlapping schedules. Enable conflict_detection in config/zap.php for detailed conflict reports.

3. Time Periods:

   • Verify time periods with dd($schedule->periods) to ensure they match expectations.

Configuration Quirks

1. Buffer Minutes:

   • Adjust time_slots.buffer_minutes in config/zap.php to control the gap between appointments.

2. Default Rules:

   • Modify default_rules to change the default behavior for new schedules (e.g., no_overlap).

3. Validation:

   • Customize validation rules in config/zap.php under validation to enforce business logic.

Extension Points

1. Custom Schedule Types:

   • Extend Zap\Models\Schedule to add custom fields or logic.

2. Recurrence Patterns:

   • Add new recurrence methods by extending Zap\Recurrence\Recurrence and registering them in the service provider.

3. Event Listeners:

   • Subscribe to Zap events to trigger actions like sending notifications or updating external calendars.

4. AI Agent Support:

   • Leverage Laravel Boost skills (zap-schedules, zap-availability, zap-recurrence) for AI-assisted development and documentation.

Performance Tips

1. Indexing:

   • Ensure schedulable_id, type, and date columns are indexed for faster queries.

2. Caching:

   • Cache frequently accessed schedules or bookable slots if your application has high read loads.

3. Batch Processing:

   • Use chunking when processing large sets of schedules to avoid memory issues.