feat: read BusProNet base data from the MyE&P API

src/MyEp/Api/AccessTokenProvider.php

@@ -0,0 +1,139 @@
+<?php
+
+namespace App\MyEp\Api;
+
+use Psr\Cache\CacheItemPoolInterface;
+use Psr\Cache\InvalidArgumentException;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+use Symfony\Contracts\HttpClient\Exception\ExceptionInterface as TransportException;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+/**
+ * Obtains and caches the client_credentials access token for the MyE&P API.
+ *
+ * MyE&P issues short-lived tokens (ten minutes), so a token is kept in the shared
+ * cache until shortly before it expires rather than requested per call.
+ */
+class AccessTokenProvider
+{
+    private const CACHE_KEY = 'myep.api.access_token';
+
+    /**
+     * Assumed token lifetime when the response omits expires_in.
+     */
+    private const DEFAULT_LIFETIME = 600;
+
+    /**
+     * Dropped from every lifetime so a token is never handed out in the seconds
+     * before it expires.
+     */
+    private const EXPIRY_MARGIN = 60;
+
+    private const MINIMUM_LIFETIME = 30;
+
+    private array $config;
+
+    public function __construct(
+        private readonly HttpClientInterface $myepClient,
+        private readonly CacheItemPoolInterface $cache,
+        private readonly LoggerInterface $logger,
+        array $options,
+    ) {
+        $this->config = $this->resolveOptions($options);
+    }
+
+    /**
+     * @throws ApiException
+     */
+    public function getToken(): string
+    {
+        try {
+            $item = $this->cache->getItem(self::CACHE_KEY);
+        } catch (InvalidArgumentException $e) {
+            throw new ApiException('Unable to read the cached MyE&P access token', 0, $e);
+        }
+
+        if ($item->isHit()) {
+            return $item->get();
+        }
+
+        [$token, $lifetime] = $this->requestToken();
+
+        $item->set($token);
+        $item->expiresAfter($lifetime);
+        $this->cache->save($item);
+
+        return $token;
+    }
+
+    /**
+     * Drops the cached token so the next call fetches a fresh one. Used when the API
+     * rejects a token the cache still considered valid.
+     */
+    public function invalidate(): void
+    {
+        try {
+            $this->cache->deleteItem(self::CACHE_KEY);
+        } catch (InvalidArgumentException) {
+            // the key is a constant, so it cannot be malformed; nothing to recover from
+        }
+    }
+
+    /**
+     * @return array{0: string, 1: int} the token and the seconds it may be cached for
+     *
+     * @throws ApiException
+     */
+    private function requestToken(): array
+    {
+        try {
+            $response = $this->myepClient->request('POST', $this->config['token_path'], [
+                'body' => [
+                    'grant_type' => 'client_credentials',
+                    'client_id' => $this->config['client_id'],
+                    'client_secret' => $this->config['client_secret'],
+                    'scope' => $this->config['scope'],
+                ],
+            ]);
+
+            $statusCode = $response->getStatusCode();
+            $payload = $response->toArray(false);
+        } catch (TransportException $e) {
+            $this->logger->error('Unable to obtain a MyE&P access token', [
+                'client_id' => $this->config['client_id'],
+                'exception' => $e,
+            ]);
+
+            throw new ApiException('Unable to obtain a MyE&P access token', 0, $e);
+        }
+
+        $token = $payload['access_token'] ?? null;
+
+        if (200 !== $statusCode || false === is_string($token) || '' === $token) {
+            $this->logger->error('MyE&P rejected the access token request', [
+                'client_id' => $this->config['client_id'],
+                'status_code' => $statusCode,
+                'error' => $payload['error'] ?? null,
+            ]);
+
+            throw new ApiException('MyE&P rejected the access token request with status '.$statusCode);
+        }
+
+        $expiresIn = (int) ($payload['expires_in'] ?? self::DEFAULT_LIFETIME);
+
+        return [$token, max(self::MINIMUM_LIFETIME, $expiresIn - self::EXPIRY_MARGIN)];
+    }
+
+    private function resolveOptions(array $options): array
+    {
+        $optionsResolver = new OptionsResolver();
+        $optionsResolver->setRequired(['client_id', 'client_secret']);
+        $optionsResolver->setDefaults([
+            'token_path' => 'token',
+            'scope' => 'api',
+        ]);
+
+        return $optionsResolver->resolve($options);
+    }
+}

src/MyEp/Api/ApiClient.php

@@ -0,0 +1,105 @@
+<?php
+
+namespace App\MyEp\Api;
+
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Contracts\HttpClient\Exception\ExceptionInterface as TransportException;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+/**
+ * Reads the MyE&P JSON API. Every response is validated here so that callers only
+ * ever see a decoded payload or an ApiException.
+ */
+class ApiClient
+{
+    public function __construct(
+        private readonly HttpClientInterface $myepClient,
+        private readonly AccessTokenProvider $tokens,
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    /**
+     * @throws ApiException
+     */
+    public function get(string $path, array $query = []): array
+    {
+        $response = $this->send($path, $query);
+
+        if (Response::HTTP_UNAUTHORIZED === $this->statusOf($response, $path)) {
+            // tokens live ten minutes, so one expiring mid-run is routine rather than a fault
+            $this->tokens->invalidate();
+            $response = $this->send($path, $query);
+        }
+
+        $statusCode = $this->statusOf($response, $path);
+
+        if (Response::HTTP_FORBIDDEN === $statusCode) {
+            $this->logger->error('MyE&P denied a request for lack of scope', ['path' => $path]);
+
+            throw new ApiException(sprintf('MyE&P denied "%s": the API client lacks the required scope', $path));
+        }
+
+        if ($statusCode < 200 || $statusCode >= 300) {
+            $this->logger->error('MyE&P returned an unexpected status', [
+                'path' => $path,
+                'status_code' => $statusCode,
+            ]);
+
+            throw new ApiException(sprintf('MyE&P returned status %d for "%s"', $statusCode, $path));
+        }
+
+        return $this->decode($response, $path);
+    }
+
+    private function send(string $path, array $query): ResponseInterface
+    {
+        try {
+            return $this->myepClient->request('GET', $path, [
+                'auth_bearer' => $this->tokens->getToken(),
+                'query' => $query,
+            ]);
+        } catch (TransportException $e) {
+            $this->logger->error('Request to MyE&P failed', ['path' => $path, 'exception' => $e]);
+
+            throw new ApiException(sprintf('Request to MyE&P endpoint "%s" failed', $path), 0, $e);
+        }
+    }
+
+    private function statusOf(ResponseInterface $response, string $path): int
+    {
+        try {
+            return $response->getStatusCode();
+        } catch (TransportException $e) {
+            $this->logger->error('Request to MyE&P failed', ['path' => $path, 'exception' => $e]);
+
+            throw new ApiException(sprintf('Request to MyE&P endpoint "%s" failed', $path), 0, $e);
+        }
+    }
+
+    private function decode(ResponseInterface $response, string $path): array
+    {
+        try {
+            $payload = $response->toArray(false);
+        } catch (TransportException $e) {
+            $this->logger->error('Unreadable response from MyE&P', ['path' => $path, 'exception' => $e]);
+
+            throw new ApiException(sprintf('Unreadable response from MyE&P endpoint "%s"', $path), 0, $e);
+        }
+
+        // some MyE&P endpoints report upstream failures in the body while still
+        // answering with 200, so the payload decides, not the status code
+        if (isset($payload['error'])) {
+            $this->logger->error('MyE&P reported an error', [
+                'path' => $path,
+                'error' => $payload['error'],
+            ]);
+
+            throw new ApiException(sprintf('MyE&P reported an error for "%s": %s', $path, (string) $payload['error']));
+        }
+
+        return $payload;
+    }
+}

src/MyEp/Api/ApiException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace App\MyEp\Api;
+
+class ApiException extends \RuntimeException
+{
+}

src/MyEp/Api/CountryCode.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\MyEp\Api;
+
+/**
+ * Normalizes the country code MyE&P resolves for a hotel.
+ *
+ * MyE&P maps the raw BusProNet abbreviations (D, A, AUT, DEU, …) to ISO-3166-1
+ * alpha-2 and reports the result as countryCode. Anything that is not a two letter
+ * code is dropped rather than stored: the value goes into a two character column and
+ * addresses a flag icon, so a half-mapped token is worse than no country at all.
+ */
+final class CountryCode
+{
+    public static function normalize(mixed $value): ?string
+    {
+        if (false === is_string($value)) {
+            return null;
+        }
+
+        $code = strtolower(trim($value));
+
+        return 1 === preg_match('/^[a-z]{2}$/', $code) ? $code : null;
+    }
+}

src/MyEp/Api/ResponseMapper.php

@@ -0,0 +1,146 @@
+<?php
+
+namespace App\MyEp\Api;
+
+use App\BusProNet\Model\Country;
+use App\BusProNet\Model\Hotel;
+use App\BusProNet\Model\Pickup;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Turns MyE&P list responses into the BusProNet models the application already works
+ * with, keyed the way the data providers expose them.
+ *
+ * The id MyE&P reports for hotels and pickups is the BusProNet idbuspro, so it fills
+ * both the id and the busProId of the models.
+ */
+class ResponseMapper
+{
+    public function __construct(private readonly LoggerInterface $logger)
+    {
+    }
+
+    /**
+     * @return array<int, Hotel> keyed by busProId
+     */
+    public function mapHotels(array $rows): array
+    {
+        $hotels = [];
+
+        foreach ($rows as $row) {
+            if (null === $busProId = $this->readBusProId($row, 'hotel')) {
+                continue;
+            }
+
+            $hotel = new Hotel();
+            $hotel
+                ->setId($busProId)
+                ->setBusProId($busProId)
+                ->setCode($this->readString($row, 'code'))
+                ->setName($this->readString($row, 'name'))
+                ->setCity($this->readString($row, 'city'))
+                ->setStreet($this->readString($row, 'street'))
+                ->setPhone($this->readString($row, 'phone'))
+                ->setCountry($this->readString($row, 'country'))
+                ->setCountryCode($this->readCountryCode($row))
+                ->setCostUnit($this->readString($row, 'costUnit'))
+            ;
+
+            $hotels[$busProId] = $hotel;
+        }
+
+        return $hotels;
+    }
+
+    /**
+     * @return array<int, Pickup> keyed by busProId
+     */
+    public function mapPickups(array $rows): array
+    {
+        $pickups = [];
+
+        foreach ($rows as $row) {
+            if (null === $busProId = $this->readBusProId($row, 'pickup')) {
+                continue;
+            }
+
+            $pickup = new Pickup();
+            $pickup
+                ->setId($busProId)
+                ->setBusProId($busProId)
+                ->setCode($this->readString($row, 'code'))
+                ->setCity($this->readString($row, 'city'))
+                ->setStreet($this->readString($row, 'street'))
+            ;
+
+            // the time is a property of a boarding stop on a date, never of the stop itself
+            $pickups[$busProId] = $pickup;
+        }
+
+        return $pickups;
+    }
+
+    /**
+     * @return array<string, Country> keyed by token
+     */
+    public function mapCountries(array $rows): array
+    {
+        $countries = [];
+
+        foreach ($rows as $row) {
+            $token = is_array($row) ? $this->readString($row, 'token') : null;
+
+            if (null === $token || '' === $token) {
+                $this->logger->warning('Skipped a MyE&P country without a token', ['row' => $row]);
+                continue;
+            }
+
+            $country = new Country();
+            $country
+                ->setId(isset($row['id']) ? (int) $row['id'] : null)
+                ->setName($this->readString($row, 'name'))
+                ->setToken($token)
+                ->setNationality($this->readString($row, 'nationality'))
+            ;
+
+            $countries[$token] = $country;
+        }
+
+        return $countries;
+    }
+
+    private function readCountryCode(array $row): ?string
+    {
+        $countryCode = CountryCode::normalize($row['countryCode'] ?? null);
+
+        if (null === $countryCode && null !== ($row['country'] ?? null)) {
+            $this->logger->warning('MyE&P reported a hotel country it could not map to ISO', [
+                'id' => $row['id'] ?? null,
+                'country' => $row['country'],
+                'countryCode' => $row['countryCode'] ?? null,
+            ]);
+        }
+
+        return $countryCode;
+    }
+
+    private function readBusProId(mixed $row, string $type): ?int
+    {
+        $busProId = is_array($row) ? (int) ($row['id'] ?? 0) : 0;
+
+        if (0 === $busProId) {
+            $this->logger->warning(sprintf('Skipped a MyE&P %s without an id', $type), ['row' => $row]);
+
+            return null;
+        }
+
+        return $busProId;
+    }
+
+    private function readString(array $row, string $key): ?string
+    {
+        $value = $row[$key] ?? null;
+
+        return null === $value ? null : (string) $value;
+    }
+}

src/MyEp/Cache/StaleWhileErrorCache.php

@@ -0,0 +1,120 @@
+<?php
+
+namespace App\MyEp\Cache;
+
+use Psr\Cache\CacheItemInterface;
+use Psr\Cache\CacheItemPoolInterface;
+use Psr\Cache\InvalidArgumentException;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Caches a value and keeps the last successful one around far longer, so a MyE&P
+ * outage degrades to slightly stale master data instead of empty dropdowns.
+ *
+ * Symfony's cache contract cannot express this: it discards the item when the
+ * callback throws, which is exactly the case that needs the previous value.
+ */
+class StaleWhileErrorCache
+{
+    private const LAST_GOOD_SUFFIX = '.last_good';
+
+    /**
+     * How long a served stale value suppresses further upstream attempts. Without it
+     * every call during an outage would try again, since the fresh key stays empty.
+     */
+    private const RETRY_DELAY = 60;
+
+    public function __construct(
+        private readonly CacheItemPoolInterface $cache,
+        private readonly LoggerInterface $logger,
+        private readonly int $staleLifetime = 604800,
+    ) {
+    }
+
+    /**
+     * @param callable(): array $producer
+     */
+    public function get(string $key, int $ttl, callable $producer): array
+    {
+        try {
+            $fresh = $this->cache->getItem($key);
+        } catch (InvalidArgumentException $e) {
+            $this->logger->error('Unusable MyE&P cache key', ['key' => $key, 'exception' => $e]);
+
+            return $this->produceUncached($key, $producer);
+        }
+
+        if ($fresh->isHit()) {
+            return $fresh->get();
+        }
+
+        try {
+            $value = $producer();
+        } catch (\Throwable $e) {
+            return $this->serveStale($key, $fresh, $e);
+        }
+
+        $fresh->set($value);
+        $fresh->expiresAfter($ttl);
+        $this->cache->save($fresh);
+
+        $this->saveLastGood($key, $value);
+
+        return $value;
+    }
+
+    private function serveStale(string $key, CacheItemInterface $fresh, \Throwable $e): array
+    {
+        try {
+            $lastGood = $this->cache->getItem($key.self::LAST_GOOD_SUFFIX);
+        } catch (InvalidArgumentException) {
+            $lastGood = null;
+        }
+
+        if (null === $lastGood || false === $lastGood->isHit()) {
+            $this->logger->error('MyE&P request failed and no previous data is cached', [
+                'key' => $key,
+                'exception' => $e,
+            ]);
+
+            return [];
+        }
+
+        $this->logger->error('MyE&P request failed, serving the last known data', [
+            'key' => $key,
+            'exception' => $e,
+        ]);
+
+        $stale = $lastGood->get();
+
+        $fresh->set($stale);
+        $fresh->expiresAfter(self::RETRY_DELAY);
+        $this->cache->save($fresh);
+
+        return $stale;
+    }
+
+    private function saveLastGood(string $key, array $value): void
+    {
+        try {
+            $lastGood = $this->cache->getItem($key.self::LAST_GOOD_SUFFIX);
+        } catch (InvalidArgumentException) {
+            return;
+        }
+
+        $lastGood->set($value);
+        $lastGood->expiresAfter($this->staleLifetime);
+        $this->cache->save($lastGood);
+    }
+
+    private function produceUncached(string $key, callable $producer): array
+    {
+        try {
+            return $producer();
+        } catch (\Throwable $e) {
+            $this->logger->error('MyE&P request failed', ['key' => $key, 'exception' => $e]);
+
+            return [];
+        }
+    }
+}

src/MyEp/Import/DestinationRow.php

@@ -0,0 +1,155 @@
+<?php
+
+namespace App\MyEp\Import;
+
+use App\MyEp\Api\CountryCode;
+
+/**
+ * One travel date at one hotel, as the MyE&P travel export reports it. This is the
+ * unit the destination table is keyed on.
+ */
+class DestinationRow
+{
+    public function __construct(
+        public readonly int $busProId,
+        public readonly string $code,
+        public readonly string $product,
+        public readonly \DateTimeImmutable $dateFrom,
+        public readonly \DateTimeImmutable $dateTo,
+        public readonly int $hotelBusProId,
+        public readonly string $hotelCode,
+        public readonly string $hotelName,
+        public readonly ?string $costUnit,
+        /** lowercase ISO-3166-1 alpha-2, null when MyE&P could not resolve one */
+        public readonly ?string $country,
+        public readonly array $pickups,
+    ) {
+    }
+
+    /**
+     * @throws InvalidRowException
+     */
+    public static function fromArray(array $data): self
+    {
+        $hotel = $data['hotel'] ?? null;
+
+        if (false === is_array($hotel)) {
+            throw new InvalidRowException('Travel export row without a hotel');
+        }
+
+        $busProId = (int) ($data['busProId'] ?? 0);
+        $hotelBusProId = (int) ($hotel['busProId'] ?? 0);
+
+        if (0 === $busProId || 0 === $hotelBusProId) {
+            throw new InvalidRowException(sprintf('Travel export row with an unusable id pair (%d, %d)', $busProId, $hotelBusProId));
+        }
+
+        return new self(
+            $busProId,
+            (string) ($data['code'] ?? ''),
+            (string) ($data['product'] ?? ''),
+            self::readDate($data, 'dateFrom'),
+            self::readDate($data, 'dateTo'),
+            $hotelBusProId,
+            (string) ($hotel['code'] ?? ''),
+            (string) ($hotel['name'] ?? ''),
+            self::readNullableString($hotel, 'costUnit'),
+            CountryCode::normalize($hotel['countryCode'] ?? null),
+            self::readPickups($data['pickups'] ?? []),
+        );
+    }
+
+    /**
+     * The columns an existing destination is refreshed with. The hotel name and code
+     * are part of it because they do change upstream, and rows that keep an outdated
+     * name drop out of the house matching.
+     */
+    public function toUpdatePayload(\DateTimeImmutable $now): array
+    {
+        return [
+            'code' => $this->code,
+            'date_from' => $this->dateFrom->format('Y-m-d'),
+            'date_to' => $this->dateTo->format('Y-m-d'),
+            'product' => $this->product,
+            'hotel' => $this->hotelName,
+            'hotel_code' => $this->hotelCode,
+            'pickups' => json_encode($this->pickups),
+            'cost_unit' => $this->costUnit,
+            'country' => $this->country,
+            'updated_at' => $now->format('Y-m-d H:i:s'),
+        ];
+    }
+
+    public function toInsertPayload(\DateTimeImmutable $now): array
+    {
+        return [
+            'code' => $this->code,
+            'bus_pro_id' => $this->busProId,
+            'date_from' => $this->dateFrom->format('Y-m-d'),
+            'date_to' => $this->dateTo->format('Y-m-d'),
+            'product' => $this->product,
+            'hotel' => $this->hotelName,
+            'hotel_code' => $this->hotelCode,
+            'hotel_bus_pro_id' => $this->hotelBusProId,
+            'pickups' => json_encode($this->pickups),
+            'cost_unit' => $this->costUnit,
+            'country' => $this->country,
+            'created_at' => $now->format('Y-m-d H:i:s'),
+        ];
+    }
+
+    /**
+     * @throws InvalidRowException
+     */
+    private static function readDate(array $data, string $key): \DateTimeImmutable
+    {
+        $value = $data[$key] ?? null;
+
+        if (false === is_string($value) || false === $date = \DateTimeImmutable::createFromFormat('!Y-m-d', $value)) {
+            throw new InvalidRowException(sprintf('Travel export row with an unreadable %s', $key));
+        }
+
+        return $date;
+    }
+
+    /**
+     * The shape here is what the destination table stores and what
+     * App\BusProNet\Model\Pickup::fromArray() reads back.
+     */
+    private static function readPickups(mixed $pickups): array
+    {
+        if (false === is_array($pickups)) {
+            return [];
+        }
+
+        $mapped = [];
+
+        foreach ($pickups as $pickup) {
+            if (false === is_array($pickup)) {
+                continue;
+            }
+
+            $busProId = (int) ($pickup['busProId'] ?? 0);
+
+            if (0 === $busProId) {
+                continue;
+            }
+
+            $mapped[] = [
+                'busProId' => $busProId,
+                'city' => self::readNullableString($pickup, 'city'),
+                'street' => self::readNullableString($pickup, 'street'),
+                'time' => self::readNullableString($pickup, 'time'),
+            ];
+        }
+
+        return $mapped;
+    }
+
+    private static function readNullableString(array $data, string $key): ?string
+    {
+        $value = $data[$key] ?? null;
+
+        return null === $value ? null : (string) $value;
+    }
+}

src/MyEp/Import/InvalidRowException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace App\MyEp\Import;
+
+/**
+ * A single unusable row of the travel export. Thrown per row so the import can skip
+ * it and carry on instead of losing the whole run.
+ */
+class InvalidRowException extends \RuntimeException
+{
+}

src/MyEp/Import/TravelExportClient.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace App\MyEp\Import;
+
+use App\MyEp\Api\ApiClient;
+use App\MyEp\Api\ApiException;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Reads the full travel export from MyE&P, one page at a time.
+ */
+class TravelExportClient
+{
+    private const PATH = 'api/travels/export';
+    private const PER_PAGE = 500;
+
+    /**
+     * Stops a malformed meta block from turning the import into an endless loop.
+     */
+    private const MAX_PAGES = 100;
+
+    public function __construct(
+        private readonly ApiClient $apiClient,
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    /**
+     * @return DestinationRow[]
+     *
+     * @throws ApiException
+     */
+    public function fetchAll(): array
+    {
+        $rows = [];
+        $page = 1;
+        $totalPages = 1;
+
+        do {
+            $payload = $this->apiClient->get(self::PATH, [
+                'page' => $page,
+                'perPage' => self::PER_PAGE,
+            ]);
+
+            $data = $payload['data'] ?? null;
+
+            if (false === is_array($data)) {
+                throw new ApiException('The MyE&P travel export did not contain a data list');
+            }
+
+            foreach ($data as $item) {
+                if (false === is_array($item)) {
+                    continue;
+                }
+
+                try {
+                    $rows[] = DestinationRow::fromArray($item);
+                } catch (InvalidRowException $e) {
+                    $this->logger->warning('Skipped an unusable travel export row', [
+                        'reason' => $e->getMessage(),
+                        'row' => $item,
+                    ]);
+                }
+            }
+
+            $totalPages = max(1, (int) ($payload['meta']['totalPages'] ?? 1));
+            ++$page;
+        } while ($page <= $totalPages && $page <= self::MAX_PAGES && [] !== $data);
+
+        if ($totalPages > self::MAX_PAGES) {
+            $this->logger->error('The MyE&P travel export reported more pages than are read', [
+                'total_pages' => $totalPages,
+                'max_pages' => self::MAX_PAGES,
+            ]);
+        }
+
+        return $rows;
+    }
+}