Réservation

Ajoutez la fonctionnalité de réservation multi-jours à votre site Larapen. Gérez les services, la capacité, le calendrier de disponibilité et les réservations, avec intégration de paiement optionnelle.

Cas d’utilisation

• Hôtel / Chambre d’hôtes : Les clients sélectionnent les dates d’arrivée et de départ avec tarification par nuit et limites de capacité.
• Location de salle : Les organisateurs réservent un lieu pour plusieurs jours avec des contraintes de séjour minimum/maximum.
• Location d’équipement : Les clients réservent du matériel pour une plage de dates avec détection de chevauchement des réservations.
• Propriété de vacances : Les vacanciers réservent un logement pour un séjour de plusieurs nuits avec calcul automatique du prix total.
• Camping : Les campeurs réservent un emplacement pour une plage de dates avec gestion de la capacité par emplacement.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+

Installation

Étape 1 : Placer le module

Copiez ou créez un lien symbolique du dossier booking dans le répertoire « extensions/addons » de votre Larapen :

Étape 2 : Activer le module

Allez dans Admin → Add-ons → Add-ons installés et activez Réservation.

Étape 3 : Exécuter les migrations

Cela crée 2 tables : booking_services et booking_reservations.

Étape 4 : Définir les permissions

L’add-on enregistre 9 permissions (voir Permissions). Assignez-les aux rôles administrateurs via Admin → Utilisateurs → Rôles & Permissions.

Étape 5 : Configurer

Naviguez vers Admin → Réservation → Paramètres et configurez les options de réservation et les préférences de notification. Voir Configuration.

Étape 6 : Créer des services

1. Allez dans Admin → Réservation → Services et créez au moins un service actif.
2. Définissez le prix par nuit, les contraintes de nuits min/max, la capacité maximale et le nombre maximum d’invités.
3. Téléchargez des images pour illustrer vos services (optionnel).

Configuration

Tous les paramètres sont gérés dans Admin → Réservation → Paramètres (stockés dans la table settings, groupe booking). Les valeurs par défaut sont définies dans config/booking.php.

Paramètre	Description	Défaut
booking_enabled	Afficher ou masquer la page de réservation côté visiteur.	true
booking_advance_days	Combien de jours à l’avance les clients peuvent réserver.	60
booking_min_advance_hours	Heures minimum avant qu’une réservation puisse être effectuée (empêche les réservations de dernière minute).	2
booking_notification_email	Adresse e-mail pour recevoir les notifications admin de réservation.	(vide)
booking_require_payment	Exiger le paiement avant la confirmation de réservation. S’applique uniquement aux services avec un prix > 0.	false
booking_cancellation_policy	Politique d’annulation en texte libre affichée sur la page de réservation.	(vide)
booking_service_images_enabled	Afficher les images principales sur les cartes de service. La première image attachée est utilisée comme image principale.	true
booking_service_step_title	Titre personnalisé pour l’étape de sélection du service (traduisible). Laisser vide pour utiliser la traduction par défaut.	(vide : utilise la valeur par défaut)
booking_captcha_enabled	Activer le défi CAPTCHA sur le formulaire de réservation.	false

Paramètres de notification

Paramètre	Description	Défaut
booking_notify_admin_on_new_booking	Envoyer un e-mail à l’adresse de notification lors de nouvelles réservations.	true
booking_notify_client_on_booking	Envoyer un e-mail de confirmation au client lors de la soumission de réservation.	true
booking_notify_client_on_status_change	Notifier le client lorsque le statut de la réservation change (confirmé, annulé, terminé).	true

Admin : Services

La page Services (Réservation → Services) gère votre catalogue de services réservables.

Liste des services

Un tableau triable et paginé affichant :

• Image principale (miniature avec lightbox galerie, ou icône de remplacement)
• Nom (traduisible)
• Prix par nuit (formaté avec devise)
• Capacité max
• Nombre de réservations
• Statut (badge actif/inactif)
• Position (ordre d’affichage)

Actions par ligne : Modifier, Supprimer.

Création & modification de services

Champs du service

• Nom (traduisible, requis pour la langue par défaut)
• Slug (traduisible, généré automatiquement si vide)
• Description (traduisible)
• Prix par nuit (numérique, utilisé pour calculer le prix total)
• Devise (requise, parmi les devises actives)
• Nuits min / Nuits max (contraintes de longueur de séjour)
• Nombre maximum d’invités (limite d’invités par réservation)
• Capacité max (entier, 1–100 – nombre de réservations simultanées autorisées)
• Actif bascule
• Position (ordre d’affichage)

Images du service

Chaque service supporte plusieurs images via le sélecteur de médias. Téléchargez des images depuis la bibliothèque de médias lors de la création ou de la modification d’un service.

• La première image est utilisée comme image principale, affichée sur les cartes de service côté visiteur.
• Si des images supplémentaires sont attachées, un bouton galerie apparaît sur la carte, permettant aux visiteurs de parcourir toutes les images dans une lightbox.
• Les services sans images affichent une icône de remplacement.
• L’affichage des images peut être activé/désactivé globalement via Admin → Réservation → Paramètres → Paramètres d’affichage.

Admin : Réservations

La page Réservations (Réservation → Réservations) affiche toutes les réservations dans un tableau paginé.

Liste des réservations

Filtrable par statut. Les colonnes incluent :

• Nom & e-mail du client
• Nom du service
• Date d’arrivée & date de départ
• Nombre de nuits
• Nombre d’invités
• Prix total
• Statut badge (en attente/confirmé/annulé/terminé)
• Statut du paiement (si le paiement est activé)

Des cartes de statistiques en haut affichent les totaux, le nombre en attente, les arrivées du jour, les départs du jour et les séjours actifs.

Détail de la réservation & gestion des statuts

La page de détail (Réservations → {réservation}) affiche :

• Informations client : nom, e-mail, téléphone, adresse IP, horodatage de réservation
• Informations de réservation : service, dates d’arrivée/départ, nombre de nuits, nombre d’invités, prix total
• Détails du paiement (le cas échéant) : statut, méthode, référence, horodatage de paiement
• Gestion des statuts : boutons pour changer le statut avec transitions :
  • En attente → Confirmé, Annulé
  • Confirmé → Terminé, Annulé, Revenir à En attente
  • Terminé → Revenir à Confirmé
  • Annulé → Réouvrir (retour à En attente)
• Raison d’annulation : affichée lors de l’annulation ; effacée lors de la réouverture
• Notes admin : notes internes non visibles par le client
• Notes client : notes soumises par le client lors de la réservation

Vue calendrier

La page Calendrier (Réservation → Réservations → Calendrier) fournit une vue mensuelle visuelle :

• Les réservations sont chargées via AJAX (GET admin/booking/reservations/calendar-events).
• Les réservations s’affichent comme des étendues multi-jours de la date d’arrivée à la date de départ.
• Code couleur par statut (warning=en attente, success=confirmé, danger=annulé, info=terminé).
• Cliquez sur un événement pour accéder à la page de détail de la réservation.

Admin : Paramètres

La page de paramètres (Réservation → Paramètres) est organisée en sections :

Paramètres généraux

• Activer la réservation : bascule pour afficher/masquer la page de réservation côté visiteur.
• Réservation à l’avance (jours) : jusqu’à combien de jours à l’avance les clients peuvent réserver.
• Délai minimum (heures) : empêche les réservations de dernière minute.
• Politique d’annulation : texte libre affiché sur la page de réservation.

Paiement

• Exiger le paiement : bascule. S’applique uniquement aux services avec un prix > 0.
• Un avertissement est affiché si aucun add-on de passerelle de paiement n’est actif.

Notifications

• E-mail de notification : adresse e-mail admin pour les alertes de réservation.
• Trois bascules contrôlant quels e-mails sont envoyés (voir Notifications).

CAPTCHA

• Activer le CAPTCHA sur le formulaire de réservation : bascule. Nécessite qu’un fournisseur CAPTCHA soit configuré dans les paramètres principaux.

Paramètres d’affichage

Contrôlez les éléments visuels de la page de réservation côté visiteur :

• Afficher l’image principale du service : Active/désactive l’affichage des images de service sur la page de réservation.
• Titre de l’étape service : Personnaliser le titre affiché au-dessus des cartes de service (traduisible). Laisser vide pour utiliser la traduction par défaut.

Côté visiteur : Page de réservation

La page de réservation est disponible à /{locale}/booking et fournit un assistant étape par étape.

Routes

Méthode	URL	Nom de route	Description
GET	/{locale}/booking	booking.index.localized	Page de l’assistant de réservation
POST	/{locale}/booking	booking.store.localized	Soumettre une réservation
GET	/{locale}/booking/confirmation/{reservation}	booking.confirmation.localized	Page de confirmation
GET	/{locale}/booking/my-reservations	booking.my-reservations.localized	Historique des réservations de l’utilisateur (authentification requise)

Des variantes non localisées (sans {locale}) sont également enregistrées.

Étapes de l’assistant de réservation

1. Sélectionner un service : grille de cartes affichant le nom, la description, le prix par nuit et les contraintes de séjour.
2. Sélectionner les dates : calendrier interactif pour choisir les dates d’arrivée et de départ. Vérification de disponibilité en temps réel via AJAX.
3. Invités : saisie du nombre d’invités (si le nombre maximum d’invités est configuré).
4. Vos coordonnées : nom, e-mail, téléphone (optionnel), notes (optionnel). Pré-rempli pour les utilisateurs authentifiés.
5. Confirmer : récapitulatif avec plage de dates, nombre de nuits, prix total. Le bouton de soumission déclenche la réservation.

API de disponibilité

Deux endpoints JSON alimentent le calendrier côté visiteur et la vérification de disponibilité :

Page de confirmation

Après une réservation réussie (ou un paiement réussi), l’utilisateur est redirigé vers /{locale}/booking/confirmation/{reservation}.

• Affiche un message de succès avec les détails de la réservation.
• Affiche le nom du service, les dates d’arrivée/départ, le nombre de nuits et le prix total.
• Note de statut expliquant que la réservation est en attente de confirmation.
• Liens vers « Retour à l’accueil » et « Réserver à nouveau ».

Paiement

Lorsque booking_require_payment est activé et que la réservation a un prix total > 0, le flux de réservation redirige vers une page de paiement au lieu de la page de confirmation.

Routes

Méthode	URL	Nom de route	Description
GET	/{locale}/booking/checkout/{reservation}	booking.checkout.localized	Page de paiement
POST	/{locale}/booking/checkout/{reservation}	booking.checkout.process.localized	Traiter le paiement

Interface Payable

Le modèle Reservation implémente l’interface App\Contracts\Payable, fournissant :

• getPayableAmount() : retourne le prix total
• getPayableCurrency() : depuis la devise du service ou la devise par défaut du site
• getPayableDescription() : ex. « Réservation : Chambre Deluxe du 15 au 18 mars 2026 »
• getPayableCustomerEmail(), getPayableCustomerName()
• markAsPaid() : définit le statut à Confirmé, payment_status à « paid »
• markPaymentFailed() : définit payment_status à « failed »
• getPaymentSuccessUrl() : redirige vers la page de confirmation
• getPaymentCancelUrl() : redirige vers la page de paiement

Passerelles de paiement supportées

La page de paiement fonctionne avec tout add-on de passerelle de paiement actif :

• Stripe : Payment Intents côté client avec Stripe.js
• PayPal : paiement par redirection
• Paddle : superposition inline ou redirection
• MoMo : mobile money avec saisie du numéro de téléphone

Mes réservations

Les utilisateurs authentifiés peuvent consulter leur historique de réservations à /{locale}/booking/my-reservations.

• Correspond aux réservations par user_id ou client_email (couvre les réservations faites avant l’inscription).
• Liste paginée (15 par page) triée par date décroissante.
• Chaque entrée affiche : nom du service, dates d’arrivée/départ, nombre de nuits, badge de statut et statut du paiement.

Cette page est également accessible depuis le menu du compte utilisateur via le lien « Mes réservations » (enregistré dans addon.json sous provides.user_menu).

Notifications

L’add-on utilise le système de Notification de Laravel avec des destinataires de courrier à la demande. Toutes les notifications sont envoyées via le service BookingManager et capturent silencieusement toute erreur d’envoi.

Classe de notification	Destinataire	Déclencheur	Paramètre
BookingConfirmationNotification	Client	Réservation créée (après paiement, si requis)	notify_client_on_booking
NewBookingAdminNotification	Admin (notification_email)	Réservation créée	notify_admin_on_new_booking
BookingStatusChangeNotification	Client	Statut changé en confirmé/annulé/terminé	notify_client_on_status_change

Chaque notification adapte son objet et son contenu pour inclure les détails de la réservation : nom du service, dates d’arrivée et de départ, nombre de nuits et prix total.

Mise à jour

Étape 1 : Remplacer les fichiers

Remplacez le répertoire du module par la nouvelle version.

Étape 2 : Exécuter les migrations

Étape 3 : Reconstruire les assets

Requis si la mise à jour inclut des fichiers SCSS/JS de thème nouveaux ou modifiés.

Étape 4 : Vider les caches

Dépannage

Le calendrier n’affiche aucun jour disponible

• Assurez-vous qu’au moins un service actif existe.
• Vérifiez que booking_advance_days est défini à une valeur supérieure à 0.
• Vérifiez que booking_enabled est défini sur true dans les paramètres.

Mode réservation : « dates non disponibles » malgré un calendrier vide

• Vérifiez les contraintes de nuits min/max sur le service. Un séjour de 2 nuits sur un service avec min_nights = 3 échouera.
• Assurez-vous que max_capacity est correctement défini. Une capacité de 1 signifie qu’une seule réservation peut occuper une date donnée.
• La détection de chevauchement empêche les doubles réservations : le système compte les réservations occupant chaque date et compare avec max_capacity.

La page de réservation retourne une erreur 404

• Assurez-vous que booking_enabled est défini sur true dans les paramètres. Le contrôleur retourne une 404 lorsque la réservation est désactivée.
• Vérifiez que le module est activé dans Admin → Add-ons.

Le client ne reçoit pas les e-mails de confirmation

• Vérifiez que booking_notify_client_on_booking est activé dans les paramètres.
• Vérifiez que votre configuration mail fonctionne (SMTP, Mailgun, etc.) dans Admin → Paramètres → Mail.
• Les échecs de notification sont capturés silencieusement : consultez storage/logs/laravel.log pour toute erreur.

La page de paiement n’affiche aucun moyen de paiement

• Assurez-vous qu’au moins un add-on de passerelle de paiement (Stripe, PayPal, Paddle ou MoMo) est installé et activé.
• Vérifiez que la passerelle est correctement configurée avec les clés API dans ses propres paramètres.
• PaymentService::getAvailableGateways() ne retourne que les passerelles entièrement configurées.

Les notifications de changement de statut ne s’envoient pas

• Le ReservationObserver gère les notifications de changement de statut. Assurez-vous qu’il est enregistré dans BookingServiceProvider::boot().
• Seules les transitions vers Confirmé, Annulé ou Terminé déclenchent les notifications client.