myep/src/Service/ParticipantEligibilityChecker.php

<?php

declare(strict_types=1);

namespace App\Service;

use App\BusProNet\Constants;
use App\BusProNet\Model\Service;
use App\Form\Model\BookingDto;
use App\Form\Service\ServiceAgeEvaluator;

/**
 * Service for evaluating participant eligibility for booking.
 *
 * Ski passes gate the booking process: a participant who cannot obtain one cannot book.
 * This service owns that gate and distinguishes the two cases the travel data allows:
 *
 * - The travel offers ski passes, but none is selectable for the participant (age rules,
 *   sold out, Buchungsstop) - the participant is ineligible and all service fields are hidden.
 * - The travel offers no ski passes at all - rare, but legitimate. There is nothing to gate
 *   on, so the participant is eligible and books without a pass, exactly like a baby does.
 *
 * Selectability is evaluated through the same pipeline the form uses to build the ski pass
 * choices (ServiceAgeEvaluator + ServiceAvailabilityCalculator), so eligibility and the
 * rendered choices cannot disagree.
 *
 * Results are cached per request using instance-level arrays to avoid redundant calculations
 * when checking the same participant multiple times.
 */
class ParticipantEligibilityChecker
{
    /** @var array<string, bool> Request-scoped cache for participant eligibility */
    private array $eligibilityCache = [];

    public function __construct(
        private readonly ServiceAgeEvaluator $serviceAgeEvaluator,
        private readonly ServiceAvailabilityCalculator $serviceAvailabilityCalculator,
    ) {
    }

    /**
     * Checks if a participant is eligible for booking.
     *
     * Returns true when the participant can book services, false when the booking process
     * would be a dead end because no ski pass can be obtained for them.
     *
     * Baby age exemption: Participants aged 0-2 years (at travel date) are always eligible
     * regardless of skipass availability, as babies don't require ski passes.
     *
     * Results are cached per request to avoid redundant calculations.
     *
     * @param BookingDto $bookingDto       The current booking data
     * @param int        $participantIndex The index of the participant being evaluated
     *
     * @return bool True if participant is eligible (has a selectable skipass or needs none)
     */
    public function isParticipantEligible(BookingDto $bookingDto, int $participantIndex): bool
    {
        $participant = $bookingDto->getParticipant($participantIndex);

        if (null === $participant || null === $participant->dateOfBirth) {
            return false;
        }

        // Create cache key based on participant's birth date, travel date, and index.
        // Selections of the other participants feed into availability but cannot change
        // within a single request, so they need no representation in the key.
        $cacheKey = sprintf(
            'participant_eligibility_%s_%s_%d',
            $participant->dateOfBirth->format('Y-m-d'),
            $bookingDto->travel->dateFrom->format('Y-m-d'),
            $participantIndex
        );

        return $this->eligibilityCache[$cacheKey] ??= (function () use ($bookingDto, $participantIndex) {
            // Nothing gates the booking when no ski pass is required - baby age or a travel
            // that does not offer ski passes at all
            if (false === $this->isSkiPassRequired($bookingDto, $participantIndex)) {
                return true;
            }

            return [] !== $this->getSelectableSkiPasses($bookingDto, $participantIndex);
        })();
    }

    /**
     * Checks whether the participant has to select a ski pass to complete the booking.
     *
     * Returns false for babies, who never qualify for a pass, and for travels that offer no
     * ski passes at all, where there is nothing to select.
     *
     * Note the asymmetry with eligibility: a travel that offers passes but has none left for
     * the participant does NOT turn the pass optional. Such a booking has to stay blocked,
     * not silently go through without a pass.
     *
     * @param BookingDto $bookingDto       The current booking data
     * @param int        $participantIndex The index of the participant being evaluated
     *
     * @return bool True if a ski pass selection is required for this participant
     */
    public function isSkiPassRequired(BookingDto $bookingDto, int $participantIndex): bool
    {
        $participant = $bookingDto->getParticipant($participantIndex);

        if (null === $participant) {
            return false;
        }

        // Baby age exemption: participants at or under BABY_MAX_AGE never need a ski pass
        $age = $participant->getAge($bookingDto->travel->dateFrom);
        if (null !== $age && $age <= Constants::BABY_MAX_AGE) {
            return false;
        }

        return [] !== $this->getOfferedSkiPasses($bookingDto);
    }

    /**
     * Collects the ski passes the participant could actually select.
     *
     * Applies the same filters as the form's ski pass choices: age constraints first, then
     * availability (sold out at the API level, exhausted by the other participants of this
     * booking, or on Buchungsstop).
     *
     * @param BookingDto $bookingDto       The current booking data
     * @param int        $participantIndex The index of the participant being evaluated
     *
     * @return array<int, Service> The selectable ski pass services
     */
    private function getSelectableSkiPasses(BookingDto $bookingDto, int $participantIndex): array
    {
        $ageAppropriateSkiPasses = array_filter(
            $this->getOfferedSkiPasses($bookingDto),
            fn (Service $service) => false === $this->serviceAgeEvaluator->canEvaluate($service)
                || true === $this->serviceAgeEvaluator->isServiceAvailableForParticipant($service, $bookingDto, $participantIndex)
        );

        return $this->serviceAvailabilityCalculator->filterAvailableServices(
            $ageAppropriateSkiPasses,
            $bookingDto,
            $participantIndex
        );
    }

    /**
     * Collects the ski passes the travel offers within its date range, ignoring the participant.
     *
     * @param BookingDto $bookingDto The current booking data
     *
     * @return array<int, Service> The ski pass services offered by the travel
     */
    private function getOfferedSkiPasses(BookingDto $bookingDto): array
    {
        return $bookingDto->travel->getAdditionalServicesBySubTypes(Constants::TOKEN_SKI_PASS, true);
    }
}