Zap Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Domain-Specific Abstraction: Zap provides a clean, Laravel-native abstraction for calendar/scheduling logic, reducing boilerplate for appointment systems, resource booking (e.g., rooms, equipment), or shift management.
  • Recurrence Patterns: Supports 15+ recurrence rules (daily, weekly, monthly ordinals, custom intervals), covering 90% of real-world scheduling needs without reinventing the wheel.
  • Conflict Detection: Built-in overlap validation for appointments/blocked times, with configurable rules (e.g., noOverlap(), maxDuration()).
  • Metadata Support: Attach arbitrary data to schedules (e.g., patient_id, organizer), enabling downstream integrations (e.g., CRM, billing).
  • Query Flexibility: Methods like getBookableSlots(), isBookableAtTime(), and schedulesForDateRange() simplify frontend/UX logic (e.g., "show available 30-minute slots").
  • AI/Boost Integration: Pre-trained Laravel Boost skills for AI agents, reducing manual API documentation efforts.

• Weaknesses:

  • Tight Coupling to Laravel Ecosystem: Assumes Laravel’s Eloquent ORM, migrations, and service container. Not framework-agnostic (e.g., no standalone PHP library).
  • UUID/ULID Complexity: Requires custom model setup if using non-integer primary keys, adding migration/config overhead.
  • Limited Customization: Advanced use cases (e.g., multi-resource dependencies, dynamic time zones) may require extending core logic.
  • No Built-in UI: Focuses on backend logic; frontend integration (e.g., React/Vue components) is manual.

Integration Feasibility

• Pros:

  • Laravel 13+ Compatibility: Minimal version constraints (PHP 8.5+) align with modern Laravel stacks.
  • Migration-First Design: Published migrations and config files simplify adoption.
  • Trait-Based: HasSchedules trait enables incremental adoption (e.g., add scheduling to Doctor model without touching other models).
  • Facade/Helper Methods: Zap::for($model) and zap()->... provide fluent syntax familiar to Laravel devs.
  • Zero Dependents: No downstream package conflicts (unlike mature packages like spatie/laravel-schedule).

• Cons:

  • Database Schema: Adds 3 tables (schedules, schedule_periods, schedule_metadata) and indexes, requiring schema migrations.
  • Primary Key Assumptions: Defaults to integer IDs; UUID/ULID support is opt-in but non-trivial.
  • Time Zone Handling: Week-boundary logic requires explicit timezone normalization (fixed in v1.15.0).
  • No Soft Deletes: Hard deletes may conflict with Laravel’s SoftDeletes trait (workaround: extend Schedule model).

Technical Risk

Key Questions for Stakeholders

1. Primary Use Case:

   • Are you building a appointment system (e.g., healthcare), resource booking (e.g., meeting rooms), or shift management (e.g., employees)? Zap’s examples align closely with these.
   • Do you need multi-resource dependencies (e.g., booking a room and an AV technician)? If so, evaluate if Zap’s single-model design suffices or if a custom solution is needed.

2. Data Model:

   • Are your models using integer primary keys? If not, budget time for UUID/ULID configuration.
   • Do you use soft deletes? If so, plan to extend the Schedule model to support SoftDeletes.

3. Scalability:

   • How many schedulable resources (e.g., doctors, rooms) and schedules per resource will you manage? Test with your expected scale (e.g., 10K schedules).
   • Will you query historical data (e.g., "show all appointments from 2023")? Zap’s design prioritizes forward-looking queries.

4. Frontend Integration:

   • Do you need real-time availability updates? Zap provides the data layer; pair with Laravel Echo/Pusher or a frontend library like react-big-calendar.
   • Will you support drag-and-drop rescheduling? Zap’s conflict detection helps, but UI logic (e.g., handling overlaps) may require custom frontend code.

5. Customization Needs:

   • Do you need custom validation rules beyond Zap’s defaults (e.g., "no double-booking for the same patient")? Extend the Schedule model or use metadata.
   • Will you integrate with external calendars (e.g., Google Calendar)? Zap’s data model is agnostic; use a sync layer (e.g., Laravel Jobs) to bridge gaps.

6. Team Skills:

   • Is your team familiar with Laravel’s Eloquent and migration patterns? Zap’s adoption assumes moderate Laravel experience.
   • Do you use AI agents (e.g., Laravel Boost)? Zap’s pre-trained skills can accelerate development but may not cover 100% of your domain logic.

Integration Approach

Stack Fit

• Laravel-Centric: Zap is optimized for Laravel 13+ and leverages:

  • Eloquent ORM for models (HasSchedules trait).
  • Service container for dependency injection (ZapServiceProvider).
  • Artisan commands for migrations/config publishing.
  • Facades/helpers for fluent syntax (zap()->for($model)).

• PHP 8.5+ Features: Uses named arguments, enums (internally), and modern type hints.

• Database Agnostic: Works with MySQL, PostgreSQL, SQLite, etc., but assumes standard Laravel database conventions.

• Compatibility Notes:

  • Laravel 12: Use v1.14.x (last compatible version).
  • PHP 8.1–8.4: Not supported (minimum PHP 8.5).
  • Non-Laravel PHP: Not applicable; Zap is Laravel-specific.

Migration Path

1. Pre-Integration:

   • Audit Dependencies: Ensure your composer.json meets PHP 8.5+ and Laravel 13+ requirements.
   • Backup Database: Zap’s migrations are idempotent but should be tested in a staging environment.
   • Review Models: Identify which models need HasSchedules (e.g., Doctor, Room, Employee).

2. Installation:

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

   • Custom Primary Keys: If using UUIDs/ULIDs, follow the Custom Model Support guide before running migrations.

3. Database Migration:

   php artisan migrate
   

   • Verify Schema: Check the generated schedules, schedule_periods, and schedule_metadata tables.
   • Indexes: Zap adds indexes on schedulable_id, type, and starts_at for performance.

4. Model Integration: Add the HasSchedules trait to your models:

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

5. Configuration:

   • Publish and customize config/zap.php:
     • time_slots.buffer_minutes: Adjust buffer time for bookable slots (default: 15).
     • default_rules.no_overlap: Set to false if overlaps are allowed.
     • conflict_detection: Enable/disable overlap checks.

6. Testing:

   • Unit Tests: Write tests for core scheduling logic (e.g., Doctor::getBookableSlots()).
   • Edge Cases: Test recurrence rules (e.g., "last Monday of the month") in