feat: voucher purchase flow

src/Controller/Voucher/AbstractVoucherPurchaseController.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Controller\Voucher;
+
+use App\Form\Model\VoucherPurchaseDto;
+use App\Htmx\HxTrait;
+use App\Service\VoucherPurchaseSessionManager;
+use App\Service\VoucherThumbnailResolver;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\RedirectResponse;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Shared base for the steps of the voucher purchase flow.
+ */
+abstract class AbstractVoucherPurchaseController extends AbstractController
+{
+    use HxTrait;
+
+    public const array STEP_ROUTES = [
+        1 => 'app_voucher_step_1',
+        2 => 'app_voucher_step_2',
+        3 => 'app_voucher_step_3',
+    ];
+
+    public function __construct(
+        protected readonly VoucherPurchaseSessionManager $sessionManager,
+        protected readonly VoucherThumbnailResolver $thumbnailResolver,
+    ) {
+    }
+
+    protected function createSessionExpiredResponse(Request $request): Response
+    {
+        $this->addFlash('error', 'Deine Sitzung ist abgelaufen. Bitte starte den Gutscheinkauf neu.');
+
+        return $this->htmxRedirect($request, $this->generateUrl('app_voucher_error'));
+    }
+
+    protected function validateStepAccess(VoucherPurchaseDto $dto, int $expectedStep): ?RedirectResponse
+    {
+        if ($expectedStep > $dto->currentStep) {
+            $this->addFlash('error', 'Bitte erst die vorherigen Schritte abschließen.');
+
+            return $this->redirectToStep($dto->currentStep);
+        }
+
+        return null;
+    }
+
+    protected function redirectToStep(int $step): RedirectResponse
+    {
+        return $this->redirectToRoute(self::STEP_ROUTES[$step] ?? self::STEP_ROUTES[1]);
+    }
+
+    /**
+     * Context shared by every step template: the sidebar summary and the step pagination.
+     *
+     * @return array<string, mixed>
+     */
+    protected function createStepContext(VoucherPurchaseDto $dto): array
+    {
+        return [
+            'voucher' => $dto,
+            'voucherThumbnail' => null !== $dto->template ? $this->thumbnailResolver->resolve($dto->template) : null,
+            'stepRoutes' => self::STEP_ROUTES,
+        ];
+    }
+}