API Reference
Schedule Types
Understanding Zap for Laravel schedule types and their usage.
Availability - Working Hours
Define when someone/something is available. Allows overlaps.
$availability = Zap::for($doctor)
->named('Office Hours')
->availability()
->from('2025-01-01')->to('2025-12-31')
->addPeriod('09:00', '12:00') // Morning session
->addPeriod('14:00', '17:00') // Afternoon session
->weekly(['monday', 'tuesday', 'wednesday', 'thursday', 'friday'])
->save();
Appointment - Actual Bookings
Concrete appointments within availability windows. Prevents overlaps.
$appointment = Zap::for($doctor)
->named('Patient A - Checkup')
->appointment()
->from('2025-01-15')
->addPeriod('10:00', '11:00')
->withMetadata(['patient_id' => 1, 'type' => 'checkup'])
->save();
Blocked - Unavailable Time
Time periods that block scheduling (lunch, holidays). Prevents overlaps.
$lunchBreak = Zap::for($doctor)
->named('Lunch Break')
->blocked()
->from('2025-01-01')->to('2025-12-31')
->addPeriod('12:00', '13:00')
->weekly(['monday', 'tuesday', 'wednesday', 'thursday', 'friday'])
->save();
Custom - Flexible Scheduling
Default type with explicit rule control.
$custom = Zap::for($user)
->named('Custom Event')
->custom()
->from('2025-01-15')
->addPeriod('15:00', '16:00')
->noOverlap() // Explicitly prevent overlaps
->save();
Querying by Type
// Query schedules by type
$availability = Schedule::availability()->get();
$appointments = Schedule::appointments()->get();
$blocked = Schedule::blocked()->get();
// Using relationship methods
$userAppointments = $user->appointmentSchedules()->get();
$userAvailability = $user->availabilitySchedules()->get();
// Check schedule type
if ($schedule->isAvailability()) {
// Handle availability schedule
}
if ($schedule->isAppointment()) {
// Handle appointment schedule
}
if ($schedule->isBlocked()) {
// Handle blocked schedule
}
Buffer Time Support
Buffer time can be added to availability slots to create gaps between appointments:
// Get availability slots with 15-minute buffer between appointments
$slots = $doctor->getAvailableSlots('2025-01-01', '09:00', '17:00', 60, 15);
// Configure global buffer time in config/zap.php
'time_slots' => [
'buffer_minutes' => 10, // Default buffer for all slots
],
See the Availability & Conflicts documentation for detailed buffer time usage.
Bookable Slots
Use getBookableSlots() to get slots that respect your availability schedules:
// Get bookable slots that intersect with availability periods
$slots = $doctor->getBookableSlots('2025-01-01', 60, 15);
// Find next bookable slot
$nextSlot = $doctor->getNextBookableSlot('2025-01-01', 90, 10);
See Bookable Slots Documentation for detailed usage.
Real-World Example: Hospital System
// Doctor's working hours (availability)
$availability = Zap::for($doctor)
->named('Dr. Smith - Office Hours')
->availability()
->from('2025-01-01')->to('2025-12-31')
->addPeriod('09:00', '12:00')
->addPeriod('14:00', '17:00')
->weekly(['monday', 'tuesday', 'wednesday', 'thursday', 'friday'])
->save();
// Lunch break (blocked)
$lunchBreak = Zap::for($doctor)
->named('Lunch Break')
->blocked()
->from('2025-01-01')->to('2025-12-31')
->addPeriod('12:00', '13:00')
->weekly(['monday', 'tuesday', 'wednesday', 'thursday', 'friday'])
->save();
// Patient appointment
$appointment = Zap::for($doctor)
->named('Patient A - Consultation')
->appointment()
->from('2025-01-15')
->addPeriod('10:00', '11:00')
->withMetadata(['patient_id' => 1, 'type' => 'consultation'])
->save();