feat: add a paginated travel export for the teamer app

src/Controller/Api/ExportController.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Controller\Api;
+
+use App\Model\TravelExportQuery;
+use App\Service\TravelExportBuilder;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Attribute\MapQueryString;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Security\Http\Attribute\IsGranted;
+
+/**
+ * Bulk exports, for consumers that mirror our data rather than query it per row.
+ *
+ * Deliberately its own resource rather than a verb hung off the collection it exports.
+ * `/api/travels/{dateCode}` accepts an arbitrary string, so an `/api/travels/export` would
+ * share a namespace with every date code and could only be kept apart from one by a
+ * negative lookahead on the sibling route -- a constraint nothing in the URL announces and
+ * which silently mis-routes when it is wrong. Under `/api/exports` the collision does not
+ * exist: this prefix never takes a parameterised segment, exactly like `/api/contingents`.
+ */
+#[Route('/api/exports')]
+#[IsGranted('ROLE_OAUTH2_API')]
+class ExportController extends AbstractController
+{
+    public function __construct(
+        private readonly TravelExportBuilder $travelExportBuilder,
+    ) {
+    }
+
+    /**
+     * Every travel date x hotel pair with its pickups resolved, paginated.
+     *
+     * The counters in meta describe the whole export, not the page, so they repeat
+     * unchanged on every page and a consumer can abort after the first one.
+     */
+    #[Route(path: '/travels', name: 'api_exports_travels', methods: ['GET'])]
+    public function travels(
+        #[MapQueryString(validationFailedStatusCode: Response::HTTP_BAD_REQUEST)]
+        TravelExportQuery $query = new TravelExportQuery(),
+    ): JsonResponse {
+        // Deliberately not wrapped in a catch that answers 200 with an error body, the way
+        // TravelController::hotelAvailability() does: the consumer's retry logic keys on
+        // status codes, so a failure here has to surface as a 5xx.
+        $export = $this->travelExportBuilder->build();
+
+        $total = count($export->rows);
+
+        return $this->json([
+            'data' => array_slice($export->rows, ($query->page - 1) * $query->perPage, $query->perPage),
+            'meta' => [
+                'page' => $query->page,
+                'perPage' => $query->perPage,
+                'total' => $total,
+                'totalPages' => (int) ceil($total / $query->perPage),
+                'skipped' => $export->skipped,
+                'pickupsWithoutMasterData' => $export->pickupsWithoutMasterData,
+                'generatedAt' => $export->generatedAt->format('c'),
+            ],
+        ]);
+    }
+}