wip: prepare transportation services

src/BusProNet/Utility/DirectionMapper.php

@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BusProNet\Utility;
+
+/**
+ * Handles direction mapping between BusProNet's inconsistent direction codes.
+ *
+ * BusProNet uses different direction codes in different contexts:
+ * - Travel data: 'HIN' (outbound), 'RUECK' (inbound)
+ * - Booking data: 'H' (outbound), 'R' (inbound)
+ *
+ * This utility provides consistent mapping between formats and enables
+ * clean English naming for internal application use.
+ */
+final class DirectionMapper
+{
+    // Travel data format (full German words)
+    public const OUTBOUND_TRAVEL = 'HIN';
+    public const INBOUND_TRAVEL = 'RUECK';
+
+    // Booking data format (single letter abbreviations)
+    public const OUTBOUND_BOOKING = 'H';
+    public const INBOUND_BOOKING = 'R';
+
+    /**
+     * Maps travel direction code to booking direction code.
+     *
+     * @param string $travelDirection The travel direction code ('HIN' or 'RUECK')
+     *
+     * @return string The booking direction code ('H' or 'R')
+     *
+     * @throws \InvalidArgumentException When direction code is not recognized
+     */
+    public static function travelToBooking(string $travelDirection): string
+    {
+        return match ($travelDirection) {
+            self::OUTBOUND_TRAVEL => self::OUTBOUND_BOOKING,
+            self::INBOUND_TRAVEL => self::INBOUND_BOOKING,
+            default => throw new \InvalidArgumentException("Unknown travel direction: $travelDirection"),
+        };
+    }
+
+    /**
+     * Maps booking direction code to travel direction code.
+     *
+     * @param string $bookingDirection The booking direction code ('H' or 'R')
+     *
+     * @return string The travel direction code ('HIN' or 'RUECK')
+     *
+     * @throws \InvalidArgumentException When direction code is not recognized
+     */
+    public static function bookingToTravel(string $bookingDirection): string
+    {
+        return match ($bookingDirection) {
+            self::OUTBOUND_BOOKING => self::OUTBOUND_TRAVEL,
+            self::INBOUND_BOOKING => self::INBOUND_TRAVEL,
+            default => throw new \InvalidArgumentException("Unknown booking direction: $bookingDirection"),
+        };
+    }
+
+    /**
+     * Gets all outbound direction codes.
+     *
+     * @return string[] Array of outbound direction codes in all formats
+     */
+    public static function getOutboundCodes(): array
+    {
+        return [self::OUTBOUND_TRAVEL, self::OUTBOUND_BOOKING];
+    }
+
+    /**
+     * Gets all inbound direction codes.
+     *
+     * @return string[] Array of inbound direction codes in all formats
+     */
+    public static function getInboundCodes(): array
+    {
+        return [self::INBOUND_TRAVEL, self::INBOUND_BOOKING];
+    }
+
+    /**
+     * Checks if a direction code is outbound.
+     *
+     * @param string $direction The direction code to check
+     *
+     * @return bool True if the direction is outbound, false otherwise
+     */
+    public static function isOutbound(string $direction): bool
+    {
+        return in_array($direction, self::getOutboundCodes(), true);
+    }
+
+    /**
+     * Checks if a direction code is inbound.
+     *
+     * @param string $direction The direction code to check
+     *
+     * @return bool True if the direction is inbound, false otherwise
+     */
+    public static function isInbound(string $direction): bool
+    {
+        return in_array($direction, self::getInboundCodes(), true);
+    }
+
+    /**
+     * Validates that a direction code is recognized.
+     *
+     * @param string $direction The direction code to validate
+     *
+     * @return bool True if the direction is valid, false otherwise
+     */
+    public static function isValid(string $direction): bool
+    {
+        return self::isOutbound($direction) || self::isInbound($direction);
+    }
+}