feat(v3): add response decoder formats

Author: andrepimpao

composer.json

@@ -13,6 +13,7 @@
     ],
     "require": {
         "php": ">=8.1",
+        "ext-simplexml": "*",
         "nyholm/append-query-string": "^1.0",
         "php-http/cache-plugin": "^2.1",
         "php-http/client-common": "^2.7",

docs/api.md

@@ -172,17 +172,18 @@ Protected access to response decoding configuration.
 
 ```php
 $this->responses()->json();
+$this->responses()->xml();
+$this->responses()->custom($decoder);
 ```
 
-When JSON decoding is enabled:
+Available response formats:
 
-- JSON response bodies are decoded into arrays.
-- Empty response bodies become `null`.
-- Invalid JSON throws `JsonException`.
+- `raw()`: response bodies are returned as strings.
+- `json()`: response bodies are decoded into arrays; empty bodies become `null`; invalid JSON throws `JsonException`.
+- `xml()`: response bodies are decoded into `SimpleXMLElement`; empty bodies become `null`; invalid XML throws `RuntimeException`.
+- `custom()`: receives the raw PSR response and returns the value used as `Response::data()`.
 
-When JSON decoding is not enabled, `Response::data()` returns the raw response body string.
-
-This area will grow as response transforms and errors are finalized.
+When no format is configured, `raw()` is used.
 
 ## `errors(): ErrorBuilder`
 

docs/responses.md

@@ -12,7 +12,11 @@ Returns response data.
 
 When `responses()->json()` is enabled on the API, JSON bodies are decoded into arrays, empty bodies become `null`, and invalid JSON throws `JsonException`.
 
-When JSON decoding is not enabled, this returns the raw response body string.
+When `responses()->xml()` is enabled, XML bodies are decoded into `SimpleXMLElement`, empty bodies become `null`, and invalid XML throws `RuntimeException`.
+
+When `responses()->custom()` is enabled, the configured callable receives the raw PSR response and returns the value used as `Response::data()`.
+
+When no response format is configured, this returns the raw response body string.
 
 ```php
 $data = $response->data();

docs/v3-architecture-plan.md

@@ -342,6 +342,7 @@ The v3 test utilities should focus on helping SDK authors test resources, respon
 - Do not add a generic collection object in the first phase. A future `collect()` helper can be considered later if arrays become limiting.
 - Symfony EventDispatcher has been replaced with a smaller request/response pipeline.
 - v3-native hooks are represented by `HookBuilder`, `RequestContext`, and `ResponseContext`.
+- Response body decoding is represented by `ResponseDecoder` and `ResponseFormat`; transport returns raw PSR responses and does not decode. Common formats use `raw()`, `json()`, and `xml()`, while custom response decoding uses `custom()`.
 - Method constants are not central to v3 because resources expose `get`, `post`, `put`, `patch`, and `delete` helpers.
 - Prefer fluent configuration over public getters.
 - Use HTTPlug `PluginClientBuilder` behavior for plugin priority ordering and same-priority plugin preservation.

src/Api.php

@@ -2,6 +2,7 @@
 
 namespace ProgrammatorDev\Api;
 
+use JsonException;
 use ProgrammatorDev\Api\Builder\AuthBuilder;
 use ProgrammatorDev\Api\Builder\CacheBuilder;
 use ProgrammatorDev\Api\Builder\ClientBuilder;
@@ -12,11 +13,12 @@
 use ProgrammatorDev\Api\Builder\ResponseBuilder;
 use ProgrammatorDev\Api\Context\ErrorContext;
 use ProgrammatorDev\Api\Request\RequestOptions;
-use Psr\Http\Client\ClientExceptionInterface as ClientException;
+use Psr\Http\Client\ClientExceptionInterface;
 use Psr\Http\Client\ClientInterface;
 use Psr\Cache\CacheItemPoolInterface;
-use Psr\Http\Message\ResponseInterface;
 use Psr\Log\LoggerInterface;
+use RuntimeException;
+use Throwable;
 
 class Api
 {
@@ -56,7 +58,10 @@ public function __construct()
     }
 
     /**
-     * @throws ClientException
+     * @throws ClientExceptionInterface
+     * @throws JsonException
+     * @throws RuntimeException
+     * @throws Throwable
      */
     public function send(
         string $method,
@@ -77,7 +82,7 @@ public function send(
         );
 
         $apiResponse = new Response(
-            data: $this->getResponseData($response),
+            data: $this->responseDecoder()->decode($response),
             rawResponse: $response,
             context: $context
         );
@@ -188,19 +193,8 @@ private function transport(): Transport
         );
     }
 
-    private function getResponseData(ResponseInterface $response): mixed
+    private function responseDecoder(): ResponseDecoder
     {
-        $response->getBody()->rewind();
-        $contents = $response->getBody()->getContents();
-
-        if (!$this->responseBuilder->shouldDecodeJson()) {
-            return $contents;
-        }
-
-        if ($contents === '') {
-            return null;
-        }
-
-        return json_decode($contents, true, flags: JSON_THROW_ON_ERROR);
+        return new ResponseDecoder($this->responseBuilder);
     }
 }

src/Builder/ErrorBuilder.php

@@ -51,6 +51,9 @@ public function when(callable $handler): self
         return $this;
     }
 
+    /**
+     * @throws \Throwable
+     */
     public function throwIfMatched(ErrorContext $context): void
     {
         $handler = $this->statusHandlers[$context->statusCode()] ?? null;

src/Builder/HookBuilder.php

@@ -38,6 +38,9 @@ public function afterResponse(callable $hook, int $priority = 0): self
         return $this;
     }
 
+    /**
+     * @throws UnexpectedValueException
+     */
     public function applyBeforeRequestHooks(RequestContext $context): RequestInterface
     {
         $request = $context->request();
@@ -59,6 +62,9 @@ public function applyBeforeRequestHooks(RequestContext $context): RequestInterfa
         return $request;
     }
 
+    /**
+     * @throws UnexpectedValueException
+     */
     public function applyAfterResponseHooks(ResponseContext $context): ResponseInterface
     {
         $response = $context->response();

src/Builder/ResponseBuilder.php

@@ -2,19 +2,61 @@
 
 namespace ProgrammatorDev\Api\Builder;
 
+use ProgrammatorDev\Api\ResponseFormat;
+use Psr\Http\Message\ResponseInterface;
+
 class ResponseBuilder
 {
-    private bool $decodeJson = false;
+    private ResponseFormat $format = ResponseFormat::Raw;
+
+    /** @var null|callable(ResponseInterface): mixed */
+    private $customDecoder = null;
+
+    public function raw(): self
+    {
+        $this->format = ResponseFormat::Raw;
+        $this->customDecoder = null;
+
+        return $this;
+    }
 
     public function json(): self
     {
-        $this->decodeJson = true;
+        $this->format = ResponseFormat::Json;
+        $this->customDecoder = null;
+
+        return $this;
+    }
+
+    public function xml(): self
+    {
+        $this->format = ResponseFormat::Xml;
+        $this->customDecoder = null;
+
+        return $this;
+    }
+
+    /**
+     * @param callable(ResponseInterface): mixed $decoder
+     */
+    public function custom(callable $decoder): self
+    {
+        $this->format = ResponseFormat::Custom;
+        $this->customDecoder = $decoder;
 
         return $this;
     }
 
-    public function shouldDecodeJson(): bool
+    public function format(): ResponseFormat
+    {
+        return $this->format;
+    }
+
+    /**
+     * @return null|callable(ResponseInterface): mixed
+     */
+    public function customDecoder(): ?callable
     {
-        return $this->decodeJson;
+        return $this->customDecoder;
     }
 }

src/ResponseDecoder.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace ProgrammatorDev\Api;
+
+use ProgrammatorDev\Api\Builder\ResponseBuilder;
+use Psr\Http\Message\ResponseInterface;
+use RuntimeException;
+use SimpleXMLElement;
+
+final class ResponseDecoder
+{
+    public function __construct(
+        private readonly ResponseBuilder $responseBuilder
+    ) {}
+
+    /**
+     * @throws \JsonException
+     * @throws RuntimeException
+     */
+    public function decode(ResponseInterface $response): mixed
+    {
+        $response->getBody()->rewind();
+        $contents = $response->getBody()->getContents();
+
+        return match ($this->responseBuilder->format()) {
+            ResponseFormat::Raw => $contents,
+            ResponseFormat::Json => $this->decodeJson($contents),
+            ResponseFormat::Xml => $this->decodeXml($contents),
+            ResponseFormat::Custom => $this->decodeCustom($response),
+        };
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    private function decodeJson(string $contents): mixed
+    {
+        return $contents === ''
+            ? null
+            : json_decode($contents, true, flags: JSON_THROW_ON_ERROR);
+    }
+
+    private function decodeXml(string $contents): ?SimpleXMLElement
+    {
+        if ($contents === '') {
+            return null;
+        }
+
+        $previous = libxml_use_internal_errors(true);
+        libxml_clear_errors();
+
+        $xml = simplexml_load_string($contents);
+        $errors = libxml_get_errors();
+
+        libxml_clear_errors();
+        libxml_use_internal_errors($previous);
+
+        if (!$xml instanceof SimpleXMLElement) {
+            $message = $errors[0]->message ?? 'Invalid XML response body.';
+
+            throw new RuntimeException(trim($message));
+        }
+
+        return $xml;
+    }
+
+    private function decodeCustom(ResponseInterface $response): mixed
+    {
+        $decoder = $this->responseBuilder->customDecoder();
+
+        if ($decoder === null) {
+            throw new RuntimeException('A custom response decoder must be configured.');
+        }
+
+        return $decoder($response);
+    }
+}

src/ResponseFormat.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace ProgrammatorDev\Api;
+
+enum ResponseFormat
+{
+    case Raw;
+    case Json;
+    case Xml;
+    case Custom;
+}