feat: voucher purchase flow

src/BusProNet/XmlParser/VoucherTemplatesParser.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BusProNet\XmlParser;
+
+use App\BusProNet\Model\VoucherTemplate;
+use App\BusProNet\Model\VoucherTemplates;
+use Symfony\Component\DomCrawler\Crawler;
+
+/**
+ * Parses GUTSCHEINVORLAGEN responses.
+ *
+ * Expected XML structure (test system, 2026-10-01):
+ * <ergebnis>
+ *     <satz typ="GUTSCHEINVORLAGEN"></satz>
+ *     <gutscheinminbetrag>10</gutscheinminbetrag>
+ *     <gutscheinmaxbetrag>5000</gutscheinmaxbetrag>
+ *     <gutscheine>
+ *         <gutschein idgutscheinvorlage="3">
+ *             <gutscheinart>K</gutscheinart>
+ *             <bezeichnung>Allgemein</bezeichnung>
+ *             <hinweis></hinweis>
+ *         </gutschein>
+ *     </gutscheine>
+ * </ergebnis>
+ */
+final class VoucherTemplatesParser extends AbstractParser
+{
+    public function parse(Crawler $node): VoucherTemplates
+    {
+        $minAmount = $this->getStringOrNullValue($node->filterXPath('//gutscheinminbetrag'));
+        $maxAmount = $this->getStringOrNullValue($node->filterXPath('//gutscheinmaxbetrag'));
+        if (null === $minAmount || '' === trim($minAmount) || null === $maxAmount || '' === trim($maxAmount)) {
+            throw new \InvalidArgumentException('Missing voucher amount bounds in voucher templates response.');
+        }
+
+        $templates = [];
+        $node->filterXPath('//gutscheine/gutschein')->each(function (Crawler $templateNode) use (&$templates): void {
+            $note = $this->getStringOrNullValue($templateNode->filterXPath('//hinweis'));
+
+            $templates[] = new VoucherTemplate(
+                id: (int) $this->getRequiredAttrValue($templateNode, 'idgutscheinvorlage', 'voucher template'),
+                type: trim($this->getStringOrNullValue($templateNode->filterXPath('//gutscheinart')) ?? ''),
+                label: trim($this->getStringOrNullValue($templateNode->filterXPath('//bezeichnung')) ?? ''),
+                note: null !== $note && '' !== trim($note) ? trim($note) : null,
+            );
+        });
+
+        return new VoucherTemplates(
+            // whole euros: the flow only offers whole-euro amounts, so the bounds are kept as such
+            minAmount: (int) ceil($this->stringToFloat($minAmount)),
+            maxAmount: (int) floor($this->stringToFloat($maxAmount)),
+            templates: $templates,
+        );
+    }
+}