wip

src/Contracts/ResourceDecorator.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Mollie\Api\Contracts;
+
+use Mollie\Api\Http\Response;
+use Mollie\Api\Resources\BaseCollection;
+use Mollie\Api\Resources\BaseResource;
+use Mollie\Api\Resources\LazyCollection;
+
+interface ResourceDecorator
+{
+    /**
+     * @param Response|BaseResource|BaseCollection|LazyCollection $resource
+     */
+    public static function fromResource($resource): self;
+}

src/Http/Requests/ResourceHydratableRequest.php

@@ -3,42 +3,63 @@
 namespace Mollie\Api\Http\Requests;
 
 use Mollie\Api\Http\Request;
+use Mollie\Api\Resources\DecorateResource;
 
 abstract class ResourceHydratableRequest extends Request
 {
     /**
-     * The resource class the request should be hydrated into.
+     * The original resource class the request should be hydrated into.
      *
      * @var string|null
      */
     protected $hydratableResource = null;
 
+    /**
+     * The custom resource class the request should be hydrated into.
+     *
+     * @var string|null|DecorateResource
+     */
+    protected ?string $customHydratableResource = null;
+
     public function isHydratable(): bool
     {
-        return $this->hydratableResource !== null;
+        return $this->hydratableResource !== null || $this->customHydratableResource !== null;
     }
 
-    public function getHydratableResource(): string
+    /**
+     * @return string|DecorateResource
+     */
+    public function getHydratableResource()
     {
         if (! $this->isHydratable()) {
             throw new \RuntimeException('Resource class is not set.');
         }
 
-        return $this->hydratableResource;
+        return $this->customHydratableResource ?? $this->hydratableResource;
     }
 
-    public function setHydratableResource(string $hydratableResource): self
+    /**
+     * @param string|DecorateResource $hydratableResource
+     * @return self
+     */
+    public function setHydratableResource($hydratableResource): self
     {
         if (! class_exists($hydratableResource)) {
             throw new \InvalidArgumentException("The resource class '{$hydratableResource}' does not exist.");
         }
 
-        /** @phpstan-ignore-next-line */
-        if ($this->hydratableResource && ! is_subclass_of($hydratableResource, $this->hydratableResource)) {
-            throw new \InvalidArgumentException("The resource class '{$hydratableResource}' does not match the existing resource class '{$this->hydratableResource}'.");
+        if ($hydratableResource instanceof DecorateResource && ! $hydratableResource->getDecorator()) {
+            throw new \InvalidArgumentException("The decorator class is not set.");
         }
 
-        $this->hydratableResource = $hydratableResource;
+        $this->customHydratableResource = $hydratableResource;
+
+        return $this;
+    }
+
+    public function resetHydratableResource(): self
+    {
+        $this->customHydratableResource = null;
 
         return $this;
     }

src/Resources/DecorateResource.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Mollie\Api\Resources;
+
+use Mollie\Api\Contracts\ResourceDecorator;
+
+class DecorateResource
+{
+    protected string $decoratedResource;
+
+    protected ?string $decorator = null;
+
+    public function __construct(string $decoratedResource)
+    {
+        $this->decoratedResource = $decoratedResource;
+    }
+
+    public function with(string $decorator): self
+    {
+        if (! is_subclass_of($decorator, ResourceDecorator::class)) {
+            throw new \InvalidArgumentException("The decorator class '{$decorator}' does not implement the DecoratedResource interface.");
+        }
+
+        $this->decorator = $decorator;
+
+        return $this;
+    }
+
+    public function getDecoratedResource(): string
+    {
+        return $this->decoratedResource;
+    }
+
+    public function getDecorator(): ?string
+    {
+        return $this->decorator;
+    }
+}

src/Resources/Onboarding.php

@@ -47,7 +47,7 @@ public function needsData(): bool
         return $this->status === OnboardingStatus::NEEDS_DATA;
     }
 
-    public function isInReview(): bool
+    public function inReview(): bool
     {
         return $this->status === OnboardingStatus::IN_REVIEW;
     }

src/Resources/ResourceCollection.php

@@ -12,7 +12,7 @@ abstract class ResourceCollection extends BaseCollection
     public static function getResourceClass(): string
     {
         if (empty(static::$resource)) {
-            throw new \RuntimeException('Collection name not set');
+            throw new \RuntimeException('Resource name not set');
         }
 
         return static::$resource;

src/Resources/ResourceFactory.php

@@ -3,6 +3,7 @@
 namespace Mollie\Api\Resources;
 
 use Mollie\Api\Contracts\Connector;
+use Mollie\Api\Contracts\ResourceDecorator;
 use Mollie\Api\Contracts\EmbeddedResourcesContract;
 use Mollie\Api\Exceptions\EmbeddedResourcesNotParseableException;
 use Mollie\Api\Http\Response;
@@ -37,6 +38,42 @@ public static function createFromApiResult(Connector $connector, $data, string $
         return $resource;
     }
 
+    /**
+     * @param  null|array|\ArrayObject  $data
+     */
+    public static function createBaseResourceCollection(
+        Connector $connector,
+        string $resourceClass,
+        Response $response,
+        $data = null,
+        ?object $_links = null,
+        ?string $resourceCollectionClass = null
+    ): BaseCollection {
+        return self::instantiateBaseCollection(
+            $connector,
+            self::determineCollectionClass($resourceClass, $resourceCollectionClass),
+            self::mapToResourceObjects($connector, $data ?? [], $resourceClass, $response),
+            $response,
+            $_links
+        );
+    }
+
+    /**
+     * Create a decorated resource from a response or existing resource.
+     *
+     * @param Response|BaseResource|BaseCollection|LazyCollection $response
+     * @param string $decorator
+     * @return ResourceDecorator
+     */
+    public static function createDecoratedResource($response, string $decorator): ResourceDecorator
+    {
+        if (! is_subclass_of($decorator, ResourceDecorator::class)) {
+            throw new \InvalidArgumentException("The decorator class '{$decorator}' does not implement the ResourceDecorator interface.");
+        }
+
+        return $decorator::fromResource($response);
+    }
+
     /**
      * Check if the resource holds embedded resources
      *
@@ -105,26 +142,6 @@ private static function createEmbeddedResourceCollection(
         );
     }
 
-    /**
-     * @param  null|array|\ArrayObject  $data
-     */
-    public static function createBaseResourceCollection(
-        Connector $connector,
-        string $resourceClass,
-        Response $response,
-        $data = null,
-        ?object $_links = null,
-        ?string $resourceCollectionClass = null
-    ): BaseCollection {
-        return self::instantiateBaseCollection(
-            $connector,
-            self::determineCollectionClass($resourceClass, $resourceCollectionClass),
-            self::mapToResourceObjects($connector, $data ?? [], $resourceClass, $response),
-            $response,
-            $_links
-        );
-    }
-
     private static function instantiateBaseCollection(
         Connector $connector,
         string $collectionClass,

src/Resources/ResourceHydrator.php

@@ -18,6 +18,16 @@ public function hydrate(ResourceHydratableRequest $request, Response $response)
     {
         $targetResourceClass = $request->getHydratableResource();
 
+        if ($targetResourceClass instanceof DecorateResource) {
+            $response = $this->hydrate(
+                // Reset the hydratable resource to the original resource class.
+                $request->resetHydratableResource(),
+                $response,
+            );
+
+            return ResourceFactory::createDecoratedResource($response, $targetResourceClass->getDecorator());
+        }
+
         if ($this->isCollectionTarget($targetResourceClass)) {
             $collection = $this->buildResultCollection($response, $targetResourceClass);
 

tests/Resources/OnboardingTest.php

@@ -31,15 +31,15 @@ public function dpTestOnboardingStatuses()
     {
         return [
             [OnboardingStatus::NEEDS_DATA, 'needsData', true],
-            [OnboardingStatus::NEEDS_DATA, 'isInReview', false],
+            [OnboardingStatus::NEEDS_DATA, 'inReview', false],
             [OnboardingStatus::NEEDS_DATA, 'isCompleted', false],
 
             [OnboardingStatus::IN_REVIEW, 'needsData', false],
-            [OnboardingStatus::IN_REVIEW, 'isInReview', true],
+            [OnboardingStatus::IN_REVIEW, 'inReview', true],
             [OnboardingStatus::IN_REVIEW, 'isCompleted', false],
 
             [OnboardingStatus::COMPLETED, 'needsData', false],
-            [OnboardingStatus::COMPLETED, 'isInReview', false],
+            [OnboardingStatus::COMPLETED, 'inReview', false],
             [OnboardingStatus::COMPLETED, 'isCompleted', true],
         ];
     }