Enhanced decoding flexibility and mapping capability

Introduced iterable as the return type for decoders to allow for more flexible data structures, moving away from strict arrays. This allows the use of generators for on-demand data processing. Added a `MapperInterface` for transforming responses into objects, facilitating object-oriented handling of response data. Streamlined the creation of default decoders by defining `ChainDecoder::default` to reduce redundancy and ensure consistency across usage. A new `GenericMapper` allows custom mapping functions, providing clients with customizable response handling strategies. Additionally, `Response` now implements `JsonSerializable`, offering a standardized way to convert response data to JSON.
phanxipang · Jan 2, 2024 · d8dec9a · d8dec9a
1 parent 088f6a6
commit d8dec9a
Show file tree

Hide file tree

Showing 13 changed files with 240 additions and 32 deletions.
diff --git a/src/Contracts/DecoderInterface.php b/src/Contracts/DecoderInterface.php
@@ -9,9 +9,9 @@
 interface DecoderInterface
 {
     /**
-     * Decode response body to native array type.
+     * Decode response body.
      *
      * @throws \Fansipan\Exception\NotDecodableException if decoder is unable to decode the response
      */
-    public function decode(ResponseInterface $response): array;
+    public function decode(ResponseInterface $response): iterable;
 }
diff --git a/src/Contracts/MapperInterface.php b/src/Contracts/MapperInterface.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fansipan\Contracts;
+
+use Psr\Http\Message\ResponseInterface;
+
+interface MapperInterface extends DecoderInterface
+{
+    /**
+     * Map the response to an object.
+     */
+    public function map(ResponseInterface $response): ?object;
+}
diff --git a/src/Decoder/ChainDecoder.php b/src/Decoder/ChainDecoder.php
@@ -23,19 +23,29 @@ public function __construct(iterable $decoders)
         $this->decoders = $decoders;
     }
 
-    /**
-     * @throws \Fansipan\Exception\NotDecodableException
-     */
-    public function decode(ResponseInterface $response): array
+    public function decode(ResponseInterface $response): iterable
     {
         foreach ($this->decoders as $decoder) {
             try {
-                return $decoder->decode($response);
+                yield from $decoder->decode($response);
             } catch (NotDecodableException $e) {
                 continue;
             }
         }
+    }
+
+    /**
+     * Create default chain decoder.
+     */
+    public static function default(): self
+    {
+        $decoders = static function () {
+            yield from [
+                new JsonDecoder(),
+                new XmlDecoder(),
+            ];
+        };
 
-        throw NotDecodableException::create();
+        return new self($decoders());
     }
 }
diff --git a/src/Decoder/JsonDecoder.php b/src/Decoder/JsonDecoder.php
@@ -13,7 +13,7 @@ final class JsonDecoder implements DecoderInterface
     /**
      * @throws \Fansipan\Exception\NotDecodableException
      */
-    public function decode(ResponseInterface $response): array
+    public function decode(ResponseInterface $response): iterable
     {
         if (! $this->supports($response)) {
             throw NotDecodableException::create();

diff --git a/src/Decoder/XmlDecoder.php b/src/Decoder/XmlDecoder.php
@@ -13,7 +13,7 @@ final class XmlDecoder implements DecoderInterface
     /**
      * @throws \Fansipan\Exception\NotDecodableException
      */
-    public function decode(ResponseInterface $response): array
+    public function decode(ResponseInterface $response): iterable
     {
         if (! $this->supports($response)) {
             throw NotDecodableException::create();

diff --git a/src/Mapper/GenericMapper.php b/src/Mapper/GenericMapper.php
@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fansipan\Mapper;
+
+use Fansipan\Contracts\DecoderInterface;
+use Fansipan\Contracts\MapperInterface;
+use Fansipan\Decoder\ChainDecoder;
+use Psr\Http\Message\ResponseInterface;
+
+final class GenericMapper implements MapperInterface
+{
+    /**
+     * @var callable(iterable): ?object
+     */
+    private $onSuccess;
+
+    /**
+     * @var callable(iterable): ?object
+     */
+    private $onFailure;
+
+    /**
+     * @var DecoderInterface
+     */
+    private $decoder;
+
+    /**
+     * @param  callable(iterable): ?object $onSuccess
+     * @param  callable(iterable): ?object $onFailure
+     */
+    public function __construct(
+        callable $onSuccess,
+        callable $onFailure,
+        ?DecoderInterface $decoder = null
+    ) {
+        $this->onSuccess = $onSuccess;
+        $this->onFailure = $onFailure;
+        $this->decoder = $decoder ?? ChainDecoder::default();
+    }
+
+    public function map(ResponseInterface $response): ?object
+    {
+        $status = $response->getStatusCode();
+        $decoded = $this->decoder->decode($response);
+
+        if ($status >= 200 && $status < 300) {
+            return ($this->onSuccess)($decoded);
+        } else {
+            return ($this->onFailure)($decoded);
+        }
+    }
+
+    public function decode(ResponseInterface $response): iterable
+    {
+        return $this->decoder->decode($response);
+    }
+}
diff --git a/src/Request.php b/src/Request.php
@@ -8,8 +8,6 @@
 use Fansipan\Contracts\DecoderInterface;
 use Fansipan\Contracts\PayloadInterface;
 use Fansipan\Decoder\ChainDecoder;
-use Fansipan\Decoder\JsonDecoder;
-use Fansipan\Decoder\XmlDecoder;
 
 abstract class Request
 {
@@ -128,13 +126,6 @@ private function createPayload(): PayloadInterface
      */
     public function decoder(): DecoderInterface
     {
-        $decoders = static function () {
-            yield from [
-                new JsonDecoder(),
-                new XmlDecoder(),
-            ];
-        };
-
-        return new ChainDecoder($decoders());
+        return ChainDecoder::default();
     }
 }
diff --git a/src/Response.php b/src/Response.php
@@ -6,21 +6,22 @@
 
 use Closure;
 use Fansipan\Contracts\DecoderInterface;
+use Fansipan\Contracts\MapperInterface;
 use Fansipan\Exception\HttpException;
 use LogicException;
 use Psr\Http\Message\ResponseInterface;
 
-final class Response implements \ArrayAccess, \Stringable
+final class Response implements \ArrayAccess, \JsonSerializable, \Stringable
 {
     use Traits\Macroable;
 
     /**
-     * @var \Psr\Http\Message\ResponseInterface
+     * @var ResponseInterface
      */
     private $response;
 
     /**
-     * @var null|\Fansipan\Contracts\DecoderInterface
+     * @var null|DecoderInterface
      */
     private $decoder;
 
@@ -53,20 +54,30 @@ public function body(): string
     public function data(): array
     {
         if (! $this->decoded) {
-            $this->decoded = $this->decode();
+            $this->decoded = Util::iteratorToArray($this->decode());
         }
 
         return $this->decoded;
     }
 
     /**
-     * Decode the response body.
-     *
-     * @return array<array-key, mixed>
+     * Get the decoded body of the response as an object.
+     */
+    public function object(): ?object
+    {
+        if (! $this->decoder instanceof MapperInterface) {
+            return null;
+        }
+
+        return $this->decoder->map($this->response);
+    }
+
+    /**
+     * Get the decoded body the response.
      *
      * @throws \Fansipan\Exception\NotDecodableException
      */
-    private function decode(): array
+    public function decode(): iterable
     {
         if (! $this->decoder instanceof DecoderInterface) {
             return [];
@@ -285,10 +296,13 @@ public function offsetUnset($offset): void
         throw new LogicException('Response data may not be mutated using array access.');
     }
 
+    public function jsonSerialize(): mixed
+    {
+        return \json_encode($this->data());
+    }
+
     /**
      * Get the body of the response.
-     *
-     * @return string
      */
     public function __toString()
     {

diff --git a/src/Util.php b/src/Util.php
@@ -165,4 +165,12 @@ public static function request(Request $request, ?string $baseUri = null): Reque
                 ->createStream((string) $request->body())
         );
     }
+
+    /**
+     * Convert iterator to array.
+     */
+    public static function iteratorToArray(iterable $data): array
+    {
+        return $data instanceof \Traversable ? \iterator_to_array($data) : (array) $data;
+    }
 }
diff --git a/tests/MapperTest.php b/tests/MapperTest.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fansipan\Tests;
+
+use Fansipan\GenericConnector;
+use Fansipan\Mock\MockClient;
+use Fansipan\Mock\MockResponse;
+use Fansipan\Tests\Services\JsonPlaceholder\GetUserRequest;
+use Fansipan\Tests\Services\JsonPlaceholder\User;
+
+final class MapperTest extends TestCase
+{
+    public function test_mapper(): void
+    {
+        $client = new MockClient([
+            MockResponse::fixture(__DIR__.'/fixtures/user.json'),
+        ]);
+
+        $connector = (new GenericConnector())->withClient($client);
+        $response = $connector->send(new GetUserRequest(1));
+
+        $user = $response->object();
+
+        $this->assertInstanceOf(User::class, $user);
+        $this->assertSame(1, $user->id);
+        $this->assertSame('Leanne Graham', $user->name);
+    }
+}
diff --git a/tests/Services/HTTPBin/GetXmlRequest.php b/tests/Services/HTTPBin/GetXmlRequest.php
@@ -8,8 +8,6 @@
 
 final class GetXmlRequest extends Request
 {
-    protected $connector = Connector::class;
-
     public function endpoint(): string
     {
         return '/xml';

diff --git a/tests/Services/JsonPlaceholder/GetUserRequest.php b/tests/Services/JsonPlaceholder/GetUserRequest.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fansipan\Tests\Services\JsonPlaceholder;
+
+use Fansipan\Contracts\DecoderInterface;
+use Fansipan\Mapper\GenericMapper;
+use Fansipan\Request;
+use Fansipan\Util;
+
+final class GetUserRequest extends Request
+{
+    private $id;
+
+    public function __construct(int $id)
+    {
+        $this->id = $id;
+    }
+
+    public function endpoint(): string
+    {
+        return 'https://jsonplaceholder.typicode.com/users/'.$this->id;
+    }
+
+    public function decoder(): DecoderInterface
+    {
+        return new GenericMapper(
+            static function (iterable $data) {
+                return User::fromArray(Util::iteratorToArray($data));
+            },
+            static function (iterable $data) {
+                return User::fromArray(Util::iteratorToArray($data));
+            }
+        );
+    }
+}
diff --git a/tests/Services/JsonPlaceholder/User.php b/tests/Services/JsonPlaceholder/User.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fansipan\Tests\Services\JsonPlaceholder;
+
+final class User
+{
+    /**
+     * @var int
+     */
+    public $id;
+
+    /**
+     * @var string
+     */
+    public $name;
+
+    /**
+     * @var string
+     */
+    public $email;
+
+    /**
+     * @var string
+     */
+    public $phone;
+
+    /**
+     * @var string
+     */
+    public $website;
+
+    public static function fromArray(array $data): self
+    {
+        $self = new self();
+
+        $self->id = $data['id'] ?? 0;
+        $self->name = $data['name'] ?? '';
+        $self->email = $data['email'] ?? '';
+        $self->phone = $data['phone'] ?? '';
+        $self->website = $data['website'] ?? '';
+
+        return $self;
+    }
+}