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

2026-09-29 11:08:04 +02:00
1 parent 1505f9b50b
commit 2e9328fc51
@@ -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);
+    }
+}
@@ -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;
+    }
+}
@@ -0,0 +1,7 @@
+<?php
+
+namespace App\MyEp\Api;
+
+class ApiException extends \RuntimeException
+{
+}
@@ -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;
+    }
+}
@@ -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;
+    }
+}