Sulu Reservations Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require comsa/sulu-reservations-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Comsa\SuluReservationsBundle\SuluReservationsBundle::class => ['all' => true],
   ];
   

2. Database Migration Run migrations to create the required tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. Basic Configuration Configure the bundle in config/packages/comsa_sulu_reservations.yaml:

   comsa_sulu_reservations:
       reservation_types: ['default']  # Define your reservation types
       default_duration: 30           # Default duration in minutes
   

4. First Use Case: Creating a Reservation Use the ReservationManager service to create a reservation:

   use Comsa\SuluReservationsBundle\Manager\ReservationManager;
   
   class SomeController
   {
       public function __construct(private ReservationManager $reservationManager) {}
   
       public function createReservation()
       {
           $reservation = $this->reservationManager->create(
               'default',  // Reservation type
               '[email protected]',  // User identifier
               new \DateTime('+1 hour'),  // Start time
               60  // Duration in minutes
           );
   
           return new JsonResponse(['success' => true, 'reservation_id' => $reservation->getId()]);
       }
   }
   

Implementation Patterns

Common Workflows

1. Reservation Creation & Validation

   • Use ReservationManager for creation with validation hooks:

     $reservation = $this->reservationManager->create(
         'type',
         '[email protected]',
         $startTime,
         $duration,
         ['metadata' => ['custom_field' => 'value']]  // Optional metadata
     );
     

   • Override validation via event listeners (ReservationCreateEvent).

2. Time Slot Management

   • Fetch available slots for a given date/time range:

     $availableSlots = $this->reservationManager->getAvailableSlots(
         'type',
         new \DateTime('today'),
         new \DateTime('+2 days'),
         30  // Slot duration in minutes
     );
     

   • Block/unblock slots programmatically:

     $this->reservationManager->blockSlot('type', $startTime, $duration);
     $this->reservationManager->unblockSlot($reservationId);
     

3. User & Resource Association

   • Link reservations to users/resources (e.g., rooms, equipment):

     $reservation->setUser('[email protected]');
     $reservation->setResource('room-101');
     $this->reservationManager->save($reservation);
     

4. Recurring Reservations

   • Create recurring reservations with cron-like syntax:

     $recurringReservation = $this->reservationManager->createRecurring(
         'type',
         '[email protected]',
         '0 9 * * 1-5',  // Cron syntax (9 AM, Mon-Fri)
         60,  // Duration
         new \DateTime('2023-10-01'),  // Start date
         new \DateTime('2023-12-31')   // End date
     );
     

5. Integration with Sulu CMS

   • Use the ReservationAdmin trait to embed reservations in Sulu admin panels:

     use Comsa\SuluReservationsBundle\Admin\ReservationAdmin;
     
     class MyAdmin extends AbstractAdmin
     {
         use ReservationAdmin;
     
         // ...
     }
     

Integration Tips

• API Layer: Expose reservation endpoints via API Platform or custom controllers.
• Frontend: Use the ReservationClient (if provided) or fetch data via REST/GraphQL.
• Notifications: Listen to ReservationCreatedEvent to trigger emails/SMS:

  $eventDispatcher->addListener(ReservationCreatedEvent::class, function (ReservationCreatedEvent $event) {
      // Send notification
  });
  

• Localization: Override translation files in translations/ for multi-language support.

Gotchas and Tips

Pitfalls

1. Time Zone Handling

   • Ensure start_time and duration are in the same time zone as your application.
   • Configure default_timezone in config/packages/comsa_sulu_reservations.yaml:

     comsa_sulu_reservations:
         default_timezone: 'Europe/Berlin'
     

2. Overlapping Reservations

   • The bundle prevents overlaps by default, but custom validation may fail silently.
   • Debug with:

     $this->reservationManager->validateOverlap('type', $startTime, $duration);
     

3. Recurring Reservation Edge Cases

   • Holidays/closed days: Use ReservationRecurrenceFilter to exclude dates:

     $filter = new ReservationRecurrenceFilter();
     $filter->excludeDates(['2023-12-25']);  // Skip Christmas
     $this->reservationManager->createRecurring(..., $filter);
     

4. Performance with Large Datasets

   • Avoid fetching all reservations at once. Use pagination:

     $reservations = $this->reservationManager->findBy([
         'type' => 'default',
         'startTime' => ['>=', new \DateTime('-7 days')],
     ], 10, 0);  // Limit 10, offset 0
     

5. Caching

   • Cache getAvailableSlots() results if the data changes infrequently:

     $cacheKey = 'available_slots_' . $type . '_' . $startTime->format('Y-m-d');
     $slots = $cache->get($cacheKey, function () use ($type, $startTime) {
         return $this->reservationManager->getAvailableSlots($type, $startTime, '+1 day', 30);
     });
     

Debugging Tips

1. Enable SQL Logging Add to .env:

   DOCTRINE_DDL_LOGGING=1
   DOCTRINE_DDL_LOGGING_FORMAT=natural
   

2. Event Debugging Dump events in a listener:

   $eventDispatcher->addListener(ReservationCreatedEvent::class, function (ReservationCreatedEvent $event) {
       dump($event->getReservation()->toArray());
   });
   

3. Common Errors

   • "Reservation type not found": Ensure the type is defined in reservation_types config.
   • "Invalid duration": Check for negative values or non-integer minutes.
   • Database constraints: Run php bin/console doctrine:schema:validate after migrations.

Extension Points

1. Custom Reservation Types Extend the ReservationType class to add fields:

   class CustomReservationType extends ReservationType
   {
       public function getAdditionalFields()
       {
           return [
               'max_guests' => ['type' => 'integer', 'required' => true],
           ];
       }
   }
   

   Register in config:

   comsa_sulu_reservations:
       reservation_types:
           custom: Comsa\SuluReservationsBundle\Entity\CustomReservationType
   

2. Custom Validation Subscribe to ReservationCreateEvent:

   $eventDispatcher->addListener(ReservationCreateEvent::class, function (ReservationCreateEvent $event) {
       if ($event->getReservation()->getType() === 'vip' && $event->getReservation()->getDuration() > 120) {
           throw new \RuntimeException('VIP reservations cannot exceed 2 hours.');
       }
   });
   

3. Custom Storage Override the ReservationRepository to use a custom storage backend (e.g., Elasticsearch):

   services:
       Comsa\SuluReservationsBundle\Repository\ReservationRepository:
           class: App\Repository\CustomReservationRepository
           arguments: ['@doctrine.orm.entity_manager']
   

4. UI Customization Override Twig templates in templates/comsa_sulu_reservations/ to modify the admin interface.