包简介

Allows responding with data that is automatically converted into PSR-7 response

README 文档

README

Yii Data Response

The package allows responding with data that is automatically converted into PSR-7 response.

Requirements

PHP 8.1 - 8.5.
DOM PHP extension.

Installation

The package could be installed with Composer:

composer require yiisoft/data-response

General usage

Response Factories

The package provides response factories that create PSR-7 responses with DataStream body. The data is formatted lazily when the response body is read.

use Yiisoft\DataResponse\ResponseFactory\JsonResponseFactory;
use Yiisoft\DataResponse\Formatter\JsonFormatter;

/**
 * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
 */

$factory = new JsonResponseFactory($responseFactory, new JsonFormatter());
$response = $factory->createResponse(['key' => 'value']);

$response->getBody()->rewind();
echo $response->getBody()->getContents(); // {"key":"value"}
echo $response->getHeaderLine('Content-Type'); // application/json; charset=UTF-8

The following response factories are available:

JsonResponseFactory — creates responses with JSON-formatted body;
XmlResponseFactory — creates responses with XML-formatted body;
HtmlResponseFactory — creates responses with HTML-formatted body;
PlainTextResponseFactory — creates responses with plain text body;
DataResponseFactory — creates responses without a predefined formatter, use middleware to format.

Middleware

The package provides PSR-15 middleware that formats DataStream responses without a predefined formatter.

use Yiisoft\DataResponse\Middleware\JsonDataResponseMiddleware;
use Yiisoft\DataResponse\Formatter\JsonFormatter;

$middleware = new JsonDataResponseMiddleware(new JsonFormatter());

The following middleware are available:

HtmlDataResponseMiddleware
JsonDataResponseMiddleware
XmlDataResponseMiddleware
PlainTextDataResponseMiddleware

Content Negotiation

The package provides content negotiation via middleware and response factory.

Middleware

ContentNegotiatorDataResponseMiddleware selects a formatter based on the request's Accept header:

use Yiisoft\DataResponse\Formatter\HtmlFormatter;
use Yiisoft\DataResponse\Formatter\XmlFormatter;
use Yiisoft\DataResponse\Formatter\JsonFormatter;
use Yiisoft\DataResponse\Middleware\ContentNegotiatorDataResponseMiddleware;

$middleware = new ContentNegotiatorDataResponseMiddleware(
    formatters: [
        'text/html' => new HtmlFormatter(),
        'application/xml' => new XmlFormatter(),
        'application/json' => new JsonFormatter(),
    ],
    fallback: new JsonFormatter(),
);

The fallback parameter also accepts a RequestHandlerInterface, for example NotAcceptableRequestHandler to return a 406 response when no formatter matches.

Response Factory

ContentNegotiatorResponseFactory selects a response factory based on the request's Accept header:

use Yiisoft\DataResponse\ResponseFactory\ContentNegotiatorResponseFactory;
use Yiisoft\DataResponse\ResponseFactory\JsonResponseFactory;
use Yiisoft\DataResponse\ResponseFactory\XmlResponseFactory;

/**
 * @var JsonResponseFactory $jsonResponseFactory
 * @var XmlResponseFactory $xmlResponseFactory
 */

$factory = new ContentNegotiatorResponseFactory(
    factories: [
        'application/json' => $jsonResponseFactory,
        'application/xml' => $xmlResponseFactory,
    ],
    fallback: $jsonResponseFactory,
);

$response = $factory->createResponse($request, ['key' => 'value']);

The fallback parameter also accepts a RequestHandlerInterface, for example NotAcceptableRequestHandler to return a 406 response when no factory matches.

DataStream

DataStream is a PSR-7 stream that lazily formats data. It wraps raw data and a formatter, and performs formatting only when the stream is read. A formatter is optional at construction time, but must be set before reading the stream, otherwise a LogicException will be thrown.

use Yiisoft\DataResponse\DataStream\DataStream;
use Yiisoft\DataResponse\Formatter\JsonFormatter;
use Yiisoft\DataResponse\Formatter\XmlFormatter;

$stream = new DataStream(['key' => 'value'], new JsonFormatter());

echo (string) $stream; // {"key":"value"}

// You can change the data or formatter dynamically
$stream->changeData(['new' => 'data']);
$stream->changeFormatter(new XmlFormatter());