wip: booking process

src/BusProNet/Model/Booking.php

@@ -1,7 +1,16 @@
 <?php
 
+declare(strict_types=1);
+
 namespace App\BusProNet\Model;
 
+/**
+ * Represents a booking with participants, services, and pricing information.
+ *
+ * This class handles complete booking data including participant information,
+ * selected services, transportation details, accommodation, and pricing calculations.
+ * It provides methods to retrieve participant-specific data and calculate costs.
+ */
 class Booking
 {
     public ?int $id = null;
@@ -12,7 +21,7 @@ class Booking
     public ?int $participantCount = null;
     public ?float $price = null;
     public ?\DateTimeImmutable $bookingDate = null;
-    public ?string $travel = null;
+    public ?string $travelName = null;
     public ?int $travelId = null;
     public ?string $travelCode = null;
     public ?\DateTimeImmutable $travelDate = null;
@@ -37,6 +46,14 @@ class Booking
     public ?float $totalPrice = null;
     public ?string $travelInfoUrl = null;
 
+    /**
+     * Calculates the remaining balance for the booking.
+     *
+     * Returns the difference between the total price and any payments made.
+     * If no payment has been made, returns the full price.
+     *
+     * @return float The remaining balance amount
+     */
     public function getBalance(): float
     {
         if (null === $this->payment) {
@@ -46,6 +63,16 @@ class Booking
         return $this->price - $this->payment;
     }
 
+    /**
+     * Retrieves additional services filtered by group.
+     *
+     * Filters the additional services array based on the provided group(s).
+     * Supports both single group strings and arrays of groups.
+     *
+     * @param mixed $group The service group(s) to filter by
+     *
+     * @return array<Service> The filtered services array
+     */
     public function getAdditionalServicesByGroup(mixed $group): array
     {
         $group = (array) $group;
@@ -55,6 +82,17 @@ class Booking
         });
     }
 
+    /**
+     * Retrieves additional services for a specific participant by group.
+     *
+     * Filters additional services by group and participant index mapping.
+     * Returns services that are assigned to the specified participant.
+     *
+     * @param int $participantIndex The participant index to filter by
+     * @param mixed $group The service group(s) to filter by
+     *
+     * @return array<Service> The filtered services for the participant
+     */
     public function getAdditionalServicesForParticipantByGroup(int $participantIndex, mixed $group): array
     {
         $selectedServices = $this->getAdditionalServicesByGroup($group);
@@ -64,6 +102,17 @@ class Booking
         });
     }
 
+    /**
+     * Retrieves transportation service for a specific participant and direction.
+     *
+     * Finds the transportation service that matches the participant index
+     * and travel direction (e.g., 'H' for outbound, 'R' for return).
+     *
+     * @param int $participantIndex The participant index to search for
+     * @param string $direction The travel direction ('H' or 'R')
+     *
+     * @return Service|null The matching transportation service or null if not found
+     */
     public function getTransportationServiceForParticipantAndDirection(
         int $participantIndex,
         string $direction
@@ -80,6 +129,16 @@ class Booking
         return null;
     }
 
+    /**
+     * Retrieves pickup service for a specific participant.
+     *
+     * Finds the pickup service assigned to the specified participant
+     * from the outbound pickup services.
+     *
+     * @param int $participantIndex The participant index to search for
+     *
+     * @return Pickup|null The matching pickup service or null if not found
+     */
     public function getPickupForParticipant(int $participantIndex): ?Pickup
     {
         foreach ($this->pickupsTo as $pickup) {
@@ -91,6 +150,16 @@ class Booking
         return null;
     }
 
+    /**
+     * Retrieves room assignment for a specific participant.
+     *
+     * Finds the room assigned to the specified participant
+     * based on the room mapping configuration.
+     *
+     * @param int $participantIndex The participant index to search for
+     *
+     * @return Room|null The matching room or null if not found
+     */
     public function getRoomForParticipant(int $participantIndex): ?Room
     {
         foreach ($this->rooms as $room) {
@@ -102,6 +171,16 @@ class Booking
         return null;
     }
 
+    /**
+     * Calculates the total price for a specific participant.
+     *
+     * Sums up all services, surcharges, and room costs assigned to the participant.
+     * Includes mandatory services that apply to all participants.
+     *
+     * @param int $participantIndex The participant index to calculate for
+     *
+     * @return float The total price for the participant
+     */
     public function getPriceForParticipant(int $participantIndex): float
     {
         $price = 0.0;
@@ -126,6 +205,15 @@ class Booking
         return $price;
     }
 
+    /**
+     * Retrieves surcharges for a specific participant.
+     *
+     * Filters surcharges based on participant index mapping.
+     *
+     * @param int $participantIndex The participant index to filter by
+     *
+     * @return array<Surcharge> The surcharges assigned to the participant
+     */
     public function getSurchargesForParticipant(int $participantIndex): array
     {
         return array_filter($this->surcharges, function (Surcharge $surcharge) use ($participantIndex) {
@@ -133,6 +221,13 @@ class Booking
         });
     }
 
+    /**
+     * Calculates the total price for all participants.
+     *
+     * Sums up the individual prices for all participants in the booking.
+     *
+     * @return float The calculated total price for all participants
+     */
     public function getCalculatedTotalPrice(): float
     {
         $totalPrice = 0.0;
@@ -144,6 +239,14 @@ class Booking
         return $totalPrice;
     }
 
+    /**
+     * Determines if the booking is editable.
+     *
+     * A booking is editable if the travel date is in the future and
+     * the status is not cancelled ('S') or unknown ('U').
+     *
+     * @return bool True if the booking can be edited, false otherwise
+     */
     public function isEditable(): bool
     {
         return $this->travelDate > new \DateTimeImmutable() && false === in_array($this->status, ['S', 'U']);