Responses

A response converts an HTTP result into typed application data. Extend AbstractResponse for a raw response, AbstractJsonResponse for JSON, or AbstractXMLResponse for XML. getResponse() returns the underlying PSR response.

XML responses require PHP's SimpleXML extension (ext-simplexml). Install and enable it in each environment that uses XML responses.

Status codes and errors

The request action accepts status codes 200 and 201 by default. An endpoint can set expectedResponseStatusCode to one code or an array. For an unexpected code, AbstractApi::createFailedResponseException() selects BadRequestException for 4xx responses and ServerFailedException for other codes.

The request action wraps exceptions from body parsing and response construction in ResponseException, preserving the original cause. Existing ResponseException instances pass through unchanged. PHP Error instances, including TypeError, propagate unchanged. A response class does not need an isSuccessful() method to participate in this flow.

JSON response

The SDK parses the JSON body into GetValue before constructing your response. Keep constructor arguments named $response and $body; the factory supplies them by name. Parse required fields in the constructor:

namespace ExampleSdk\Endpoints\Units;

use Psr\Http\Message\ResponseInterface;
use WrkFlow\ApiSdkBuilder\Responses\AbstractJsonResponse;
use Wrkflow\GetValue\GetValue;

final class UnitResponse extends AbstractJsonResponse
{
    public readonly int $id;
    public readonly string $name;

    public function __construct(ResponseInterface $response, GetValue $body)
    {
        parent::__construct($response, $body);
        $this->id = $body->getRequiredInt('id');
        $this->name = $body->getRequiredString('name');
    }
}

body() returns the parsed GetValue. Invalid JSON raises InvalidJsonResponseException. Required getters validate missing or invalid fields. Convert nested records into typed Entities when useful.

Responses containing items

Extend AbstractJsonItemsResponse or AbstractXMLItemsResponse. Their constructors accept $response, $body, and $container. Keep these names.

Implement getTransformerClass(): string with the class of a GetValueTransformerContract, and getItemsKey(): string|array with the field path containing the items. The SDK container creates the transformer.

Implement items(): array by returning transformUsingArray(), with a PHPDoc return type naming your Entity. Implement loopItems(Closure $onItem): bool by calling transformUsingLoop($onItem). getRawItems() provides untransformed items. Document the callback's Entity type in your concrete response.

Pagination

Use Responses\Concerns\PaginatedResponse for pagination accessors. Initialize $itemsPerPage, $totalItems, $currentPage, and $totalPages in your response constructor from the API's metadata.

The trait exposes getItemsPerPage(), getTotalItems(), getCurrentPage(), getTotalPages(), and onLastPage(). An empty result counts as the last page.

Edit this page on GitHub Updated at Thu, Nov 5, 2026