Zap For Laravel 1.7 : Le système de gestion de calendriers pour Laravel

Zap For Laravel s’impose comme la solution de référence pour gérer calendriers, disponibilités et rendez-vous dans vos applications Laravel. Avec la sortie de la version 1.7.0 le 15 novembre 2025, le package anciennement nommé « Laravel Zap » change de nom pour s’aligner avec les standards de Laravel.

Qu’est-ce que Laravel ZAP ?

Zap For Laravel (anciennement laravel-zap) est un package open-source développé par Ludovic Guénet qui résout un problème récurrent : la gestion complexe des calendriers et plannings dans les applications web.

Que vous développiez une plateforme de réservation médicale, un système de gestion de salles de réunion ou une application de prise de rendez-vous, ZAP fournit une API fluide et des fonctionnalités robustes pour gérer les disponibilités, détecter les conflits et créer des récurrences.

Le package nécessite PHP 8.2+ et Laravel 11.0+, assurant ainsi une compatibilité avec les dernières versions de l’écosystème.

Nouveauté version 1.7.0

La version 1.7.0, sortie le 15 novembre 2025, marque un tournant stratégique pour le projet avec un rebranding complet :

Renommage du package : De laravel-zap vers zap-for-laravel
Conformité trademark Laravel : Le README et toute la documentation ont été mis à jour pour respecter les guidelines de la marque Laravel
Nouvelle identité : Le site officiel passe à zap-for-laravel.com

Ce changement de nom reflète une volonté de s’aligner sur les bonnes pratiques communautaires Laravel et d’assurer la pérennité du projet.

Installation et configuration

L’installation se fait via Composer avec le nouveau nom de package :

composer require laraveljutsu/zap

Publiez ensuite les migrations et exécutez-les :

php artisan vendor:publish --tag=zap-migrations
php artisan migrate

// Optionnel : publier le fichier de configuration
php artisan vendor:publish --tag=zap-config

Ajoutez le trait HasSchedules à vos modèles Eloquent concernés :

use Zap\Models\Concerns\HasSchedules;

class Doctor extends Authenticatable
{
    use HasSchedules;

    // Votre code existant...
}

Les quatre types de schedules

Zap For Laravel repose sur une architecture simple mais puissante avec quatre types de planification distincts, chacun ayant ses propres règles de validation :

1. Availability (Disponibilité)

Définit les créneaux où une ressource est disponible. Les chevauchements sont autorisés par défaut :

use Zap\Facades\Zap;

// Horaires de bureau d'un médecin
$availability = Zap::for($doctor)
    ->named('Horaires consultation')
    ->availability()
    ->from('2025-01-01')
    ->addPeriod('09:00', '12:00') // Session matin
    ->addPeriod('14:00', '18:00') // Session après-midi
    ->weekly(['monday', 'tuesday', 'wednesday', 'thursday', 'friday'])
    ->save();

2. Appointment (Rendez-vous)

Les rendez-vous qui ne peuvent pas se chevaucher. La détection de conflits est automatique :

use Zap\Exceptions\ScheduleConflictException;

try {
    $appointment = Zap::for($doctor)
        ->named('Consultation patient Dupont')
        ->appointment()
        ->from('2025-03-15')
        ->addPeriod('10:00', '11:00')
        ->withMetadata([
            'patient_id' => 123,
            'type' => 'consultation',
            'notes' => 'Contrôle annuel'
        ])
        ->save();
} catch (ScheduleConflictException $e) {
    // Créneau déjà pris, proposer une alternative
    $conflicts = $e->getConflictingSchedules();
}

3. Blocked (Blocage)

Représente les créneaux indisponibles comme les congés ou pauses :

// Pause déjeuner quotidienne
$lunchBreak = Zap::for($doctor)
    ->blocked()
    ->named('Pause déjeuner')
    ->from('2025-01-01')
    ->to('2025-12-31')
    ->addPeriod('12:00', '14:00')
    ->weekly(['monday', 'tuesday', 'wednesday', 'thursday', 'friday'])
    ->save();

// Congés annuels
$vacation = Zap::for($doctor)
    ->blocked()
    ->named('Congés été')
    ->from('2025-08-01')
    ->to('2025-08-31')
    ->addPeriod('00:00', '23:59')
    ->save();

4. Custom (Personnalisé)

Offre un contrôle total sur les règles de validation pour des cas d’usage spécifiques.

Vérification de disponibilité

Avant de créer un rendez-vous, vérifiez qu’un créneau est libre grâce aux méthodes du trait HasSchedules :

// Vérifier si une plage horaire est disponible
$isAvailable = $doctor->isAvailableAt(
    date: '2025-03-15',
    start: '14:00',
    end: '16:00'
);

if ($isAvailable) {
    // Créer le rendez-vous
    $appointment = Zap::for($doctor)
        ->named('Consultation urgente')
        ->appointment()
        ->from('2025-03-15')
        ->addPeriod('14:00', '16:00')
        ->save();
}

// Récupérer les créneaux disponibles d'une journée (intervalles de 30 min)
$availableSlots = $doctor->getAvailableSlots(
    date: '2025-03-15',
    dayStart: '09:00',
    dayEnd: '18:00',
    slotDuration: 30
);

// Trouver le prochain créneau libre
$nextSlot = $doctor->getNextAvailableSlot(
    afterDate: '2025-03-15',
    duration: 60, // 1 heure
    dayStart: '09:00',
    dayEnd: '18:00'
);

Cas d’usage pratique : système de réservation médicale

Voici un exemple complet d’implémentation pour un cabinet médical :

// 1. Définir les horaires de travail du praticien
$availability = Zap::for($doctor)
    ->named('Heures de consultation Dr. Martin')
    ->availability()
    ->from('2025-01-01')
    ->to('2025-12-31')
    ->addPeriod('08:30', '12:00')
    ->addPeriod('13:30', '17:30')
    ->weekly(['monday', 'tuesday', 'thursday', 'friday'])
    ->save();

// 2. Bloquer les pauses obligatoires
$break = Zap::for($doctor)
    ->blocked()
    ->named('Pause déjeuner')
    ->from('2025-01-01')
    ->addPeriod('12:00', '13:30')
    ->weekly(['monday', 'tuesday', 'thursday', 'friday'])
    ->save();

// 3. Créer un rendez-vous patient avec validation automatique
try {
    $appointment = Zap::for($doctor)
        ->named('Patient Durand - Consultation')
        ->appointment()
        ->from('2025-03-20')
        ->addPeriod('09:00', '09:30')
        ->withMetadata([
            'patient_id' => 456,
            'patient_name' => 'Jean Durand',
            'reason' => 'Contrôle post-opératoire',
            'phone' => '+33123456789'
        ])
        ->save();

    // Envoyer confirmation SMS/email

} catch (ScheduleConflictException $e) {
    // Proposer des créneaux alternatifs
    $alternatives = $doctor->getAvailableSlots(
        date: '2025-03-20',
        dayStart: '08:30',
        dayEnd: '17:30',
        slotDuration: 30
    );
}

Récurrences et patterns temporels

ZAP supporte des patterns de récurrence sophistiqués parfaits pour les horaires réguliers :

// Réunion hebdomadaire chaque lundi à 9h
$meeting = Zap::for($team)
    ->named('Standup hebdomadaire')
    ->appointment()
    ->from('2025-01-06') // Premier lundi
    ->to('2025-12-31')
    ->addPeriod('09:00', '09:30')
    ->weekly(['monday'])
    ->save();

// Astreinte week-end (samedi et dimanche)
$onCall = Zap::for($engineer)
    ->availability()
    ->named('Astreinte week-end')
    ->from('2025-01-01')
    ->to('2025-12-31')
    ->addPeriod('00:00', '23:59')
    ->weekly(['saturday', 'sunday'])
    ->save();

Points d’attention et bonnes pratiques

Gestion des fuseaux horaires : ZAP utilise Carbon pour gérer les timezones. Assurez-vous que votre configuration Laravel (config/app.php) est correcte
Performance : Le package optimise automatiquement les requêtes Eloquent. Pour des volumes importants, pensez à indexer les colonnes de dates
Validation métier : Utilisez withRule() pour adapter les règles de validation à vos besoins spécifiques
Metadata : Stockez les données contextuelles importantes via withMetadata() au format JSON
Tests : Le package fournit des helpers pour tester vos plannings dans vos tests unitaires

Pourquoi adopter Zap For Laravel ?

Zap For Laravel se distingue par plusieurs avantages clés :

API intuitive : Syntaxe fluide proche du langage naturel, facile à lire et maintenir
Détection automatique des conflits : Plus besoin de coder manuellement la logique de validation
Intégration native Laravel : Traits Eloquent, facades, events, configuration standard
Flexible et extensible : Système de règles configurable pour s’adapter à tout type de métier
Performance optimisée : Requêtes SQL optimisées et support des indexes
Maintenance active : Mises à jour régulières et communauté francophone active