@@ -32,99 +32,133 @@ composer require yiisoft/data-response
3232
3333## General usage
3434
35- The package provides ` DataResponseFactory ` class that, given a [ PSR-17] ( https://www.php-fig.org/psr/psr-17/ )
36- response factory, is able to create data response.
35+ ### Response Factories
3736
38- Data response contains raw data to be processed later.
37+ The package provides response factories that create [ PSR-7] ( https://www.php-fig.org/psr/psr-7/ ) responses
38+ with ` DataStream ` body. The data is formatted lazily when the response body is read.
3939
4040``` php
41- use Yiisoft\DataResponse\DataResponseFactory;
41+ use Yiisoft\DataResponse\ResponseFactory\JsonResponseFactory;
42+ use Yiisoft\DataResponse\Formatter\JsonFormatter;
4243
4344/**
4445 * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
4546 */
4647
47- $factory = new DataResponseFactory($responseFactory);
48- $dataResponse = $factory->createResponse('test');
49- $dataResponse
50- ->getBody()
51- ->rewind();
48+ $factory = new JsonResponseFactory($responseFactory, new JsonFormatter());
49+ $response = $factory->createResponse(['key' => 'value']);
5250
53- echo $dataResponse
54- ->getBody()
55- ->getContents( ); // "test"
51+ $response->getBody()->rewind();
52+ echo $response ->getBody()->getContents(); // {"key":"value"}
53+ echo $response->getHeaderLine('Content-Type' ); // application/json; charset=UTF-8
5654```
5755
58- ### Formatters
56+ The following response factories are available:
5957
60- Formatter purpose is to format a data response. In the following example we format data as JSON.
58+ - ` JsonResponseFactory ` — creates responses with JSON-formatted body;
59+ - ` XmlResponseFactory ` — creates responses with XML-formatted body;
60+ - ` HtmlResponseFactory ` — creates responses with HTML-formatted body;
61+ - ` PlainTextResponseFactory ` — creates responses with plain text body;
62+ - ` DataResponseFactory ` — creates responses without a predefined formatter, use middleware to format.
6163
62- ``` php
63- use Yiisoft\DataResponse\DataResponseFactory;
64- use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
64+ ### Middleware
6565
66- /**
67- * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
68- */
66+ The package provides [ PSR-15] ( https://www.php-fig.org/psr/psr-15/ ) middleware that formats ` DataStream ` responses
67+ without a predefined formatter.
68+
69+ ``` php
70+ use Yiisoft\DataResponse\Middleware\JsonDataResponseMiddleware;
71+ use Yiisoft\DataResponse\Formatter\JsonFormatter;
6972
70- $factory = new DataResponseFactory($responseFactory);
71- $dataResponse = $factory->createResponse('test');
72- $dataResponse = $dataResponse->withResponseFormatter(new JsonDataResponseFormatter());
73- $dataResponse
74- ->getBody()
75- ->rewind();
76-
77- echo $dataResponse->getHeader('Content-Type'); // ["application/json; charset=UTF-8"]
78- echo $dataResponse
79- ->getBody()
80- ->getContents(); // "test"
73+ $middleware = new JsonDataResponseMiddleware(new JsonFormatter());
8174```
8275
83- The following formatters are available:
76+ The following middleware are available:
8477
85- - ` HtmlDataResponseFormatter `
86- - ` JsonDataResponseFormatter `
87- - ` XmlDataResponseFormatter `
88- - ` PlainTextDataResponseFormatter `
78+ - ` HtmlDataResponseMiddleware `
79+ - ` JsonDataResponseMiddleware `
80+ - ` XmlDataResponseMiddleware `
81+ - ` PlainTextDataResponseMiddleware `
8982
90- ### Middleware
83+ ### Content Negotiation
9184
92- The package provides a [ PSR-15 ] ( https://www.php-fig.org/psr/psr-15/ ) middleware that is able to format a data response.
85+ The package provides content negotiation via middleware and response factory .
9386
94- ``` php
95- use Yiisoft\DataResponse\Middleware\FormatDataResponse;
96- use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
87+ #### Middleware
9788
98- $middleware = (new FormatDataResponse(new JsonDataResponseFormatter()));
99- //$middleware->process($request, $handler);
89+ ` ContentNegotiatorDataResponseMiddleware ` selects a formatter based on the request's ` Accept ` header:
90+
91+ ``` php
92+ use Yiisoft\DataResponse\Formatter\HtmlFormatter;
93+ use Yiisoft\DataResponse\Formatter\XmlFormatter;
94+ use Yiisoft\DataResponse\Formatter\JsonFormatter;
95+ use Yiisoft\DataResponse\Middleware\ContentNegotiatorDataResponseMiddleware;
96+
97+ $middleware = new ContentNegotiatorDataResponseMiddleware(
98+ formatters: [
99+ 'text/html' => new HtmlFormatter(),
100+ 'application/xml' => new XmlFormatter(),
101+ 'application/json' => new JsonFormatter(),
102+ ],
103+ fallback: new JsonFormatter(),
104+ );
100105```
101106
102- Also, the package provides [ PSR-15] ( https://www.php-fig.org/psr/psr-15/ ) middleware for content negotiation:
107+ The ` fallback ` parameter also accepts a ` RequestHandlerInterface ` , for example ` NotAcceptableRequestHandler `
108+ to return a 406 response when no formatter matches.
109+
110+ #### Response Factory
111+
112+ ` ContentNegotiatorResponseFactory ` selects a response factory based on the request's ` Accept ` header:
103113
104114``` php
105- use Yiisoft\DataResponse\Formatter\HtmlDataResponseFormatter;
106- use Yiisoft\DataResponse\Formatter\XmlDataResponseFormatter;
107- use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
108- use Yiisoft\DataResponse\Middleware\ContentNegotiator;
109-
110- $middleware = new ContentNegotiator([
111- 'text/html' => new HtmlDataResponseFormatter(),
112- 'application/xml' => new XmlDataResponseFormatter(),
113- 'application/json' => new JsonDataResponseFormatter(),
114- ]);
115+ use Yiisoft\DataResponse\ResponseFactory\ContentNegotiatorResponseFactory;
116+ use Yiisoft\DataResponse\ResponseFactory\JsonResponseFactory;
117+ use Yiisoft\DataResponse\ResponseFactory\XmlResponseFactory;
118+
119+ /**
120+ * @var JsonResponseFactory $jsonResponseFactory
121+ * @var XmlResponseFactory $xmlResponseFactory
122+ */
123+
124+ $factory = new ContentNegotiatorResponseFactory(
125+ factories: [
126+ 'application/json' => $jsonResponseFactory,
127+ 'application/xml' => $xmlResponseFactory,
128+ ],
129+ fallback: $jsonResponseFactory,
130+ );
131+
132+ $response = $factory->createResponse($request, ['key' => 'value']);
115133```
116134
117- You can override middlewares with method ` withContentFormatters() ` :
135+ The ` fallback ` parameter also accepts a ` RequestHandlerInterface ` , for example ` NotAcceptableRequestHandler `
136+ to return a 406 response when no factory matches.
137+
138+ ### DataStream
139+
140+ ` DataStream ` is a [ PSR-7] ( https://www.php-fig.org/psr/psr-7/ ) stream that lazily formats data.
141+ It wraps raw data and a formatter, and performs formatting only when the stream is read.
142+ A formatter is optional at construction time, but must be set before reading the stream,
143+ otherwise a ` LogicException ` will be thrown.
118144
119145``` php
120- $middleware->withContentFormatters([
121- 'application/xml' => new XmlDataResponseFormatter(),
122- 'application/json' => new JsonDataResponseFormatter(),
123- ]);
146+ use Yiisoft\DataResponse\DataStream\DataStream;
147+ use Yiisoft\DataResponse\Formatter\JsonFormatter;
148+ use Yiisoft\DataResponse\Formatter\XmlFormatter;
149+
150+ $stream = new DataStream(['key' => 'value'], new JsonFormatter());
151+
152+ echo (string) $stream; // {"key":"value"}
153+
154+ // You can change the data or formatter dynamically
155+ $stream->changeData(['new' => 'data']);
156+ $stream->changeFormatter(new XmlFormatter());
124157```
125158
126159## Documentation
127160
161+ - [ Deprecated classes] ( docs/deprecated.md )
128162- [ Internals] ( docs/internals.md )
129163
130164If you need help or have a question, the [ Yii Forum] ( https://forum.yiiframework.com/c/yii-3-0/63 ) is a good place for that.
0 commit comments