[PAR-848] Configurable Express Button Styles

src/BusinessLogic/CheckoutAPI/ExpressCheckout/Controller/ExpressCheckoutController.php

@@ -64,15 +64,18 @@ public function __construct(
      */
     public function isAvailable(ExpressCheckoutAvailabilityRequest $request): ExpressCheckoutAvailabilityResponse
     {
+        $available = $this->expressCheckoutService->isExpressCheckoutAvailable(
+            $request->getPage(),
+            $request->getCountry(),
+            $request->getCurrency(),
+            $request->getIpAddress(),
+            $request->getProductIds(),
+            $request->getCategoryIds()
+        );
+
         return new ExpressCheckoutAvailabilityResponse(
-            $this->expressCheckoutService->isExpressCheckoutAvailable(
-                $request->getPage(),
-                $request->getCountry(),
-                $request->getCurrency(),
-                $request->getIpAddress(),
-                $request->getProductIds(),
-                $request->getCategoryIds()
-            )
+            $available,
+            $available ? $this->resolveButtonStyle() : null
         );
     }
 
@@ -102,8 +105,13 @@ public function isAvailableForGuest(
         );
 
         $countries = $available ? $this->countryConfigurationService->getCountryCodes() : [];
+        $hasCountries = !empty($countries);
 
-        return new GuestExpressCheckoutAvailabilityResponse(!empty($countries), $countries);
+        return new GuestExpressCheckoutAvailabilityResponse(
+            $hasCountries,
+            $countries,
+            $hasCountries ? $this->resolveButtonStyle() : null
+        );
     }
 
     /**
@@ -135,4 +143,14 @@ public function solicit(ExpressCheckoutSolicitRequest $request): IdentificationF
 
         return new IdentificationFormResponse($form);
     }
+
+    /**
+     * @return string|null
+     */
+    private function resolveButtonStyle(): ?string
+    {
+        $settings = $this->expressCheckoutService->getExpressCheckoutSettings();
+
+        return $settings ? $settings->getButtonStyle() : null;
+    }
 }

src/BusinessLogic/CheckoutAPI/ExpressCheckout/Responses/ExpressCheckoutAvailabilityResponse.php

@@ -16,19 +16,29 @@ class ExpressCheckoutAvailabilityResponse extends Response
      */
     protected $available;
 
+    /**
+     * @var string|null
+     */
+    protected $buttonStyle;
+
     /**
      * @param bool $available
+     * @param string|null $buttonStyle
      */
-    public function __construct(bool $available)
+    public function __construct(bool $available, ?string $buttonStyle = null)
     {
         $this->available = $available;
+        $this->buttonStyle = $buttonStyle;
     }
 
     /**
      * @inheritDoc
      */
     public function toArray(): array
     {
-        return ['available' => $this->available];
+        return [
+            'available' => $this->available,
+            'buttonStyle' => $this->buttonStyle,
+        ];
     }
 }

src/BusinessLogic/CheckoutAPI/ExpressCheckout/Responses/GuestExpressCheckoutAvailabilityResponse.php

@@ -21,14 +21,24 @@ class GuestExpressCheckoutAvailabilityResponse extends Response
      */
     protected $availableCountries;
 
+    /**
+     * @var string|null
+     */
+    protected $buttonStyle;
+
     /**
      * @param bool $available
      * @param string[] $availableCountries ISO country codes for which Express Checkout is available.
+     * @param string|null $buttonStyle
      */
-    public function __construct(bool $available, array $availableCountries)
-    {
+    public function __construct(
+        bool $available,
+        array $availableCountries,
+        ?string $buttonStyle = null
+    ) {
         $this->available = $available;
         $this->availableCountries = $availableCountries;
+        $this->buttonStyle = $buttonStyle;
     }
 
     /**
@@ -39,6 +49,7 @@ public function toArray(): array
         return [
             'available' => $this->available,
             'availableCountries' => $this->availableCountries,
+            'buttonStyle' => $this->buttonStyle,
         ];
     }
 }

src/BusinessLogic/ConfigurationWebhookAPI/Handlers/ExpressCheckout/SaveExpressCheckoutSettingsHandler.php

@@ -7,6 +7,7 @@
 use SeQura\Core\BusinessLogic\ConfigurationWebhookAPI\Requests\ExpressCheckout\SaveExpressCheckoutSettingsRequest;
 use SeQura\Core\BusinessLogic\ConfigurationWebhookAPI\Responses\ExpressCheckout\SaveExpressCheckoutSettingsResponse;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\DuplicatedExpressCheckoutPageException;
+use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutButtonStyleException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutPageConfigException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutPageException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Services\ExpressCheckoutService;
@@ -39,6 +40,7 @@ public function __construct(ExpressCheckoutService $expressCheckoutService)
      * @throws InvalidExpressCheckoutPageException
      * @throws DuplicatedExpressCheckoutPageException
      * @throws InvalidExpressCheckoutPageConfigException
+     * @throws InvalidExpressCheckoutButtonStyleException
      */
     public function handle(array $payload): Response
     {

src/BusinessLogic/ConfigurationWebhookAPI/Requests/ExpressCheckout/SaveExpressCheckoutSettingsRequest.php

@@ -4,6 +4,7 @@
 
 use SeQura\Core\BusinessLogic\ConfigurationWebhookAPI\Requests\ConfigurationWebhookRequest;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\DuplicatedExpressCheckoutPageException;
+use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutButtonStyleException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutPageConfigException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutPageException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Models\ExpressCheckoutPageConfig;
@@ -21,12 +22,19 @@ class SaveExpressCheckoutSettingsRequest extends ConfigurationWebhookRequest
      */
     protected $expressCheckoutConfigs;
 
+    /**
+     * @var string|null
+     */
+    protected $buttonStyle;
+
     /**
      * @param ExpressCheckoutPageConfig[] $expressCheckoutConfigs
+     * @param string|null $buttonStyle
      */
-    public function __construct(array $expressCheckoutConfigs)
+    public function __construct(array $expressCheckoutConfigs, ?string $buttonStyle = null)
     {
         $this->expressCheckoutConfigs = $expressCheckoutConfigs;
+        $this->buttonStyle = $buttonStyle;
     }
 
     /**
@@ -35,6 +43,7 @@ public function __construct(array $expressCheckoutConfigs)
      * @return self
      *
      * @throws InvalidExpressCheckoutPageException
+     * @throws InvalidExpressCheckoutButtonStyleException
      */
     public static function fromPayload(array $payload): object
     {
@@ -47,17 +56,24 @@ public static function fromPayload(array $payload): object
             }
         }
 
-        return new self($configs);
+        $buttonStyle = $payload['buttonStyle'] ?? null;
+
+        if ($buttonStyle !== null && !\is_string($buttonStyle)) {
+            throw new InvalidExpressCheckoutButtonStyleException();
+        }
+
+        return new self($configs, $buttonStyle);
     }
 
     /**
      * @return ExpressCheckoutSettings
      *
      * @throws DuplicatedExpressCheckoutPageException
      * @throws InvalidExpressCheckoutPageConfigException
+     * @throws InvalidExpressCheckoutButtonStyleException
      */
     public function transformToDomainModel(): ExpressCheckoutSettings
     {
-        return new ExpressCheckoutSettings($this->expressCheckoutConfigs);
+        return new ExpressCheckoutSettings($this->expressCheckoutConfigs, $this->buttonStyle);
     }
 }

src/BusinessLogic/ConfigurationWebhookAPI/Responses/ExpressCheckout/GetExpressCheckoutSettingsResponse.php

@@ -42,6 +42,9 @@ public function toArray(): array
         $configs = $this->expressCheckoutSettings
             ? $this->expressCheckoutSettings->getExpressCheckoutConfigs()
             : [];
+        $buttonStyle = $this->expressCheckoutSettings
+            ? $this->expressCheckoutSettings->getButtonStyle()
+            : null;
 
         return [
             'availablePages' => array_map(static function (ExpressCheckoutPage $page) {
@@ -50,6 +53,7 @@ public function toArray(): array
             'expressCheckoutConfigs' => array_map(static function (ExpressCheckoutPageConfig $config) {
                 return $config->toArray();
             }, $configs),
+            'buttonStyle' => $buttonStyle,
         ];
     }
 }

src/BusinessLogic/DataAccess/ExpressCheckout/Entities/ExpressCheckoutSettings.php

@@ -3,6 +3,7 @@
 namespace SeQura\Core\BusinessLogic\DataAccess\ExpressCheckout\Entities;
 
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\DuplicatedExpressCheckoutPageException;
+use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutButtonStyleException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutPageConfigException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutPageException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Models\ExpressCheckoutPageConfig;
@@ -53,7 +54,20 @@ public function inflate(array $data): void
             }
         }
 
-        $this->expressCheckoutSettings = new DomainExpressCheckoutSettings($configs);
+        $buttonStyle = static::getDataValue($expressCheckoutSettings, 'buttonStyle', null);
+        if (!\is_string($buttonStyle)) {
+            $buttonStyle = null;
+        }
+
+        // A style is rejected when it is written, so a stored one that no longer
+        // validates means the row was corrupted or hand-edited. Dropping just the
+        // style keeps the page configs readable: the button falls back to its
+        // default look instead of every read of this row failing.
+        try {
+            $this->expressCheckoutSettings = new DomainExpressCheckoutSettings($configs, $buttonStyle);
+        } catch (InvalidExpressCheckoutButtonStyleException $exception) {
+            $this->expressCheckoutSettings = new DomainExpressCheckoutSettings($configs);
+        }
     }
 
     /**
@@ -63,11 +77,7 @@ public function toArray(): array
     {
         $data = parent::toArray();
         $data['storeId'] = $this->storeId;
-        $data['expressCheckoutSettings'] = [
-            'expressCheckoutConfigs' => array_map(static function (ExpressCheckoutPageConfig $config) {
-                return $config->toArray();
-            }, $this->expressCheckoutSettings->getExpressCheckoutConfigs()),
-        ];
+        $data['expressCheckoutSettings'] = $this->expressCheckoutSettings->toArray();
 
         return $data;
     }

src/BusinessLogic/Domain/ExpressCheckout/Exceptions/InvalidExpressCheckoutButtonStyleException.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions;
+
+use SeQura\Core\BusinessLogic\Domain\Translations\Model\BaseTranslatableException;
+use SeQura\Core\BusinessLogic\Domain\Translations\Model\TranslatableLabel;
+use Throwable;
+
+/**
+ * Class InvalidExpressCheckoutButtonStyleException.
+ *
+ * @package SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions
+ */
+class InvalidExpressCheckoutButtonStyleException extends BaseTranslatableException
+{
+    /**
+     * @var int
+     */
+    protected $code = 400;
+
+    /**
+     * @param ?Throwable $previous
+     */
+    public function __construct(?Throwable $previous = null)
+    {
+        parent::__construct(new TranslatableLabel(
+            'Invalid express checkout button style.',
+            'general.errors.expressCheckout.invalidButtonStyle'
+        ), $previous);
+    }
+}

src/BusinessLogic/Domain/ExpressCheckout/Models/ExpressCheckoutSettings.php

@@ -3,6 +3,7 @@
 namespace SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Models;
 
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\DuplicatedExpressCheckoutPageException;
+use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutButtonStyleException;
 use SeQura\Core\BusinessLogic\Domain\ExpressCheckout\Exceptions\InvalidExpressCheckoutPageConfigException;
 
 /**
@@ -14,21 +15,40 @@
  */
 class ExpressCheckoutSettings
 {
+    /**
+     * The style is an opaque blob: the keys it may carry are owned by the
+     * merchant portal and the express checkout button page, so that neither
+     * needs a release of this library to grow. Only its shape is checked here.
+     * The size ceiling is what the button page's URL query parameter can carry
+     * (integration-assets drops anything larger), and it also keeps an oversized
+     * style from truncating the serialized column it shares with the page
+     * configs.
+     */
+    private const BUTTON_STYLE_MAX_BYTES = 1536;
+
     /**
      * @var ExpressCheckoutPageConfig[]
      */
     protected $expressCheckoutConfigs;
 
+    /**
+     * @var string|null
+     */
+    protected $buttonStyle;
+
     /**
      * @param ExpressCheckoutPageConfig[] $expressCheckoutConfigs
+     * @param string|null $buttonStyle
      *
      * @throws InvalidExpressCheckoutPageConfigException When an entry is not an ExpressCheckoutPageConfig.
      * @throws DuplicatedExpressCheckoutPageException When two entries reference the same page.
+     * @throws InvalidExpressCheckoutButtonStyleException When the style is not a JSON object within the size limit.
      */
-    public function __construct(array $expressCheckoutConfigs = [])
+    public function __construct(array $expressCheckoutConfigs = [], ?string $buttonStyle = null)
     {
         $this->validateConfigs($expressCheckoutConfigs);
         $this->expressCheckoutConfigs = array_values($expressCheckoutConfigs);
+        $this->buttonStyle = $this->normalizeButtonStyle($buttonStyle);
     }
 
     /**
@@ -39,6 +59,14 @@ public function getExpressCheckoutConfigs(): array
         return $this->expressCheckoutConfigs;
     }
 
+    /**
+     * @return string|null
+     */
+    public function getButtonStyle(): ?string
+    {
+        return $this->buttonStyle;
+    }
+
     /**
      * @param string $page Page identifier string (see ExpressCheckoutPage factories).
      *
@@ -64,6 +92,7 @@ public function toArray(): array
             'expressCheckoutConfigs' => array_map(static function (ExpressCheckoutPageConfig $config) {
                 return $config->toArray();
             }, $this->expressCheckoutConfigs),
+            'buttonStyle' => $this->buttonStyle,
         ];
     }
 
@@ -95,4 +124,28 @@ private function validateConfigs(array $expressCheckoutConfigs): void
             $seenPages[] = $page;
         }
     }
+
+    /**
+     * Treats an empty style as unset and asserts that anything else is a JSON
+     * object within the size limit. A decoded scalar or list is rejected: the
+     * button page reads named properties off an object.
+     *
+     * @param string|null $buttonStyle
+     *
+     * @return string|null
+     *
+     * @throws InvalidExpressCheckoutButtonStyleException
+     */
+    private function normalizeButtonStyle(?string $buttonStyle): ?string
+    {
+        if ($buttonStyle === null || $buttonStyle === '') {
+            return null;
+        }
+
+        if (\strlen($buttonStyle) > self::BUTTON_STYLE_MAX_BYTES || !\is_object(json_decode($buttonStyle))) {
+            throw new InvalidExpressCheckoutButtonStyleException();
+        }
+
+        return $buttonStyle;
+    }
 }