Skip to content

06-responses.md

Latest commit

 

History

History
189 lines (129 loc) · 4.43 KB

06-responses.md

File metadata and controls

189 lines (129 loc) · 4.43 KB
Raw

Responses

Response mapping covers decoded data, raw PSR responses, entities, collections, envelopes, and hydration context.

Response

Response wraps decoded response data and the raw PSR response.

data()

data(): mixed

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 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.

$data = $response->data();

raw()

raw(): ResponseInterface

Returns the raw PSR response.

$status = $response->raw()->getStatusCode();

entity()

entity(string $class, ?string $key = null): EntityInterface

Maps decoded response data to an entity class.

return $this
    ->endpoint()
    ->get('/users/{id}', ['id' => $id])
    ->entity(User::class, key: 'data');

The class must implement EntityInterface.

collection()

collection(string $class, ?string $key = null): array

Maps list data to a plain array of entities.

return $this
    ->endpoint()
    ->get('/users')
    ->collection(User::class, key: 'data');

envelope()

envelope(string $class): EnvelopeInterface

Maps the response to a custom envelope.

return $this
    ->endpoint()
    ->get('/users/{id}', ['id' => $id])
    ->envelope(UserEnvelope::class);

The class must implement EnvelopeInterface.

EntityInterface

Entities used by response mapping must implement:

public static function fromArray(array $data, ?Context $context = null): static;

fromArray() is the mapping boundary for an entity. The package passes decoded response data to it; the SDK author decides how payload keys become constructor arguments, value objects, or derived values.

EnvelopeInterface

Envelopes used by Response::envelope() must implement:

public static function fromResponse(Response $response, ?Context $context = null): static;

Context

Context carries SDK config and response resolution into response mapping.

SDK users do not fetch context from Response. The package passes context into entity and envelope hydration methods:

EntityInterface::fromArray(array $data, ?Context $context = null)
EnvelopeInterface::fromResponse(Response $response, ?Context $context = null)

config()

config(): Config

Returns the SDK config available while hydrating entities or envelopes.

$timezone = $context?->config()->get('timezone');

When a request is executed through a resource configured with withConfig(), this returns the effective API configuration plus its resource-local overrides. The same effective configuration is available to hooks and error handlers for that request. See Resource-Local Configuration.

resolver()

resolver(): ResolverInterface

Returns the response-graph resolver provided by the API runtime. It can follow linked entities, collections, and pagination through the configured SDK runtime. Calling it outside an API runtime request throws RuntimeException.

See Resolver for linked-resource authoring, request behavior, and memoization scope.

ErrorContext

ErrorContext is passed to configured error handlers.

$this->errors()->status(404, NotFoundException::class);
$this->errors()->statuses([
    401 => UnauthorizedException::class,
    404 => NotFoundException::class,
]);
$this->errors()->status(404, function (ErrorContext $context): Throwable {
    return new NotFoundException($context->response()->data()['message']);
});
$this->errors()->when(function (ErrorContext $context): ?Throwable {
    if (($context->response()->data()['code'] ?? null) !== 'invalid_api_key') {
        return null;
    }

    return new InvalidApiKeyException($context->response()->data()['message']);
});

It exposes:

  • response(): Response
  • apiContext(): Context
  • statusCode(): int

Navigation