Replace data response by data stream (big refactoring)

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## 2.1.3 under development
 
+- New #107: Add `DataStream` (@vjik)
+- New #107: Add `FormatterInterface` and implementations: `HtmlFormatter`, `JsonFormatter`, `PlainTextFormatter`,
+  `XmlFormatter` (@vjik)
+- New #107: Add `DataResponseFactoryInterface` and implementations: `DataResponseFactory`, `FormattedResponseFactory`,
+  `HtmlResponseFactory`, `JsonResponseFactory`, `PlainTextResponseFactory`, `XmlResponseFactory` (@vjik)
+- New #107: Add middlewares: `XmlDataResponseMiddleware`, `HtmlDataResponseMiddleware`, `JsonDataResponseMiddleware`,
+  `PlainTextDataResponseMiddleware` and `DataResponseMiddleware` (@vjik)
+- New #107: Add `ContentNegotiatorResponseFactory` and `ContentNegotiatorDataResponseMiddleware` (@vjik)
+- Chg #107: Deprecate `DataResponse`, `DataResponseFactory`, `DataResponseFactoryInterface`,
+  `DataResponseFormatterInterface`, `ResponseContentTrait`, `HtmlDataResponseFormatter`,
+  `JsonDataResponseFormatter`, `PlainTextDataResponseFormatter`, `XmlDataResponseFormatter`, `ContentNegotiator`,
+  `FormatDataResponse`, `FormatDataResponseAsHtml`, `FormatDataResponseAsJson`, `FormatDataResponseAsPlainText`,
+  `FormatDataResponseAsXml` (@vjik)
 - Enh #106: Explicitly import classes, functions, and constants in "use" section (@mspirkov)
 - Enh #108: Remove unnecessary files from Composer package (@mspirkov)
 

README.md

@@ -32,99 +32,131 @@ composer require yiisoft/data-response
 
 ## General usage
 
-The package provides `DataResponseFactory` class that, given a [PSR-17](https://www.php-fig.org/psr/psr-17/)
-response factory, is able to create data response.
+### Response Factories
 
-Data response contains raw data to be processed later.
+The package provides response factories that create [PSR-7](https://www.php-fig.org/psr/psr-7/) responses
+with `DataStream` body. The data is formatted lazily when the response body is read.
 
 ```php
-use Yiisoft\DataResponse\DataResponseFactory;
+use Yiisoft\DataResponse\ResponseFactory\JsonResponseFactory;
+use Yiisoft\DataResponse\Formatter\JsonFormatter;
 
 /**
  * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
  */
 
-$factory = new DataResponseFactory($responseFactory);
-$dataResponse = $factory->createResponse('test');
-$dataResponse
-    ->getBody()
-    ->rewind();
+$factory = new JsonResponseFactory($responseFactory, new JsonFormatter());
+$response = $factory->createResponse(['key' => 'value']);
 
-echo $dataResponse
-    ->getBody()
-    ->getContents(); // "test"
+$response->getBody()->rewind();
+echo $response->getBody()->getContents(); // {"key":"value"}
+echo $response->getHeaderLine('Content-Type'); // application/json; charset=UTF-8
 ```
 
-### Formatters
+The following response factories are available:
 
-Formatter purpose is to format a data response. In the following example we format data as JSON.
+- `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.
 
-```php
-use Yiisoft\DataResponse\DataResponseFactory;
-use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
+### Middleware
 
-/**
- * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
- */
+The package provides [PSR-15](https://www.php-fig.org/psr/psr-15/) middleware that formats `DataStream` responses
+without a predefined formatter.
+
+```php
+use Yiisoft\DataResponse\Middleware\JsonDataResponseMiddleware;
+use Yiisoft\DataResponse\Formatter\JsonFormatter;
 
-$factory = new DataResponseFactory($responseFactory);
-$dataResponse = $factory->createResponse('test');
-$dataResponse = $dataResponse->withResponseFormatter(new JsonDataResponseFormatter());
-$dataResponse
-    ->getBody()
-    ->rewind();
-
-echo $dataResponse->getHeader('Content-Type'); // ["application/json; charset=UTF-8"]
-echo $dataResponse
-    ->getBody()
-    ->getContents(); // "test"
+$middleware = new JsonDataResponseMiddleware(new JsonFormatter());
 ```
 
-The following formatters are available:
+The following middleware are available:
 
-- `HtmlDataResponseFormatter`
-- `JsonDataResponseFormatter`
-- `XmlDataResponseFormatter`
-- `PlainTextDataResponseFormatter`
+- `HtmlDataResponseMiddleware`
+- `JsonDataResponseMiddleware`
+- `XmlDataResponseMiddleware`
+- `PlainTextDataResponseMiddleware`
 
-### Middleware
+### Content Negotiation
 
-The package provides a [PSR-15](https://www.php-fig.org/psr/psr-15/) middleware that is able to format a data response.
+The package provides content negotiation via middleware and response factory.
 
-```php
-use Yiisoft\DataResponse\Middleware\FormatDataResponse;
-use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
+#### Middleware
 
-$middleware = (new FormatDataResponse(new JsonDataResponseFormatter()));
-//$middleware->process($request, $handler);
+`ContentNegotiatorDataResponseMiddleware` selects a formatter based on the request's `Accept` header:
+
+```php
+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(),
+);
 ```
 
-Also, the package provides [PSR-15](https://www.php-fig.org/psr/psr-15/) middleware for content negotiation:
+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:
 
 ```php
-use Yiisoft\DataResponse\Formatter\HtmlDataResponseFormatter;
-use Yiisoft\DataResponse\Formatter\XmlDataResponseFormatter;
-use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
-use Yiisoft\DataResponse\Middleware\ContentNegotiator;
-
-$middleware = new ContentNegotiator([
-    'text/html' => new HtmlDataResponseFormatter(),
-    'application/xml' => new XmlDataResponseFormatter(),
-    'application/json' => new JsonDataResponseFormatter(),
-]);
+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']);
 ```
 
-You can override middlewares with method `withContentFormatters()`:
+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](https://www.php-fig.org/psr/psr-7/) stream that lazily formats data.
+It wraps raw data and a formatter, and performs formatting only when the stream is read.
 
 ```php
-$middleware->withContentFormatters([
-    'application/xml' => new XmlDataResponseFormatter(),
-    'application/json' => new JsonDataResponseFormatter(),
-]);
+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());
 ```
 
 ## Documentation
 
+- [Deprecated classes](docs/deprecated.md)
 - [Internals](docs/internals.md)
 
 If 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.

composer.json

@@ -46,7 +46,8 @@
         "rector/rector": "^2.1.4",
         "roave/infection-static-analysis-plugin": "^1.35",
         "vimeo/psalm": "^5.26.1 || ^6.8.0",
-        "yiisoft/di": "^1.4"
+        "yiisoft/di": "^1.4",
+        "yiisoft/test-support": "^3.2"
     },
     "autoload": {
         "psr-4": {
@@ -82,6 +83,6 @@
     },
     "scripts": {
         "require-checker": "composer-require-checker",
-        "test": "phpunit --testdox --no-interaction"
+        "test": "phpunit --testdox"
     }
 }

config/di-web.php

@@ -2,21 +2,55 @@
 
 declare(strict_types=1);
 
-use Yiisoft\DataResponse\DataResponseFactory;
-use Yiisoft\DataResponse\DataResponseFactoryInterface;
+use Yiisoft\DataResponse\DataResponseFactory as DeprecatedDataResponseFactory;
+use Yiisoft\DataResponse\DataResponseFactoryInterface as DeprecatedDataResponseFactoryInterface;
 use Yiisoft\DataResponse\DataResponseFormatterInterface;
 use Yiisoft\DataResponse\Formatter\HtmlDataResponseFormatter;
+use Yiisoft\DataResponse\Formatter\HtmlFormatter;
+use Yiisoft\DataResponse\Formatter\JsonFormatter;
+use Yiisoft\DataResponse\Formatter\XmlFormatter;
 use Yiisoft\DataResponse\Middleware\ContentNegotiator;
+use Yiisoft\DataResponse\Middleware\ContentNegotiatorDataResponseMiddleware;
+use Yiisoft\DataResponse\NotAcceptableRequestHandler;
+use Yiisoft\DataResponse\ResponseFactory\ContentNegotiatorResponseFactory;
+use Yiisoft\DataResponse\ResponseFactory\DataResponseFactory;
+use Yiisoft\DataResponse\ResponseFactory\DataResponseFactoryInterface;
+use Yiisoft\DataResponse\ResponseFactory\HtmlResponseFactory;
+use Yiisoft\DataResponse\ResponseFactory\JsonResponseFactory;
+use Yiisoft\DataResponse\ResponseFactory\XmlResponseFactory;
 use Yiisoft\Definitions\DynamicReferencesArray;
+use Yiisoft\Definitions\Reference;
+use Yiisoft\Definitions\ReferencesArray;
 
 /* @var $params array */
 
 return [
     DataResponseFormatterInterface::class => HtmlDataResponseFormatter::class,
-    DataResponseFactoryInterface::class => DataResponseFactory::class,
+    DeprecatedDataResponseFactoryInterface::class => DeprecatedDataResponseFactory::class,
     ContentNegotiator::class => [
         '__construct()' => [
             'contentFormatters' => DynamicReferencesArray::from($params['yiisoft/data-response']['contentFormatters']),
         ],
     ],
+    DataResponseFactoryInterface::class => DataResponseFactory::class,
+    ContentNegotiatorDataResponseMiddleware::class => [
+        '__construct()' => [
+            'formatters' => ReferencesArray::from([
+                'text/html' => HtmlFormatter::class,
+                'application/xml' => XmlFormatter::class,
+                'application/json' => JsonFormatter::class,
+            ]),
+            'fallback' => Reference::to(NotAcceptableRequestHandler::class),
+        ],
+    ],
+    ContentNegotiatorResponseFactory::class => [
+        '__construct()' => [
+            'factories' => DynamicReferencesArray::from([
+                'text/html' => HtmlResponseFactory::class,
+                'application/xml' => XmlResponseFactory::class,
+                'application/json' => JsonResponseFactory::class,
+            ]),
+            'fallback' => Reference::to(NotAcceptableRequestHandler::class),
+        ],
+    ],
 ];

docs/deprecated.md

@@ -0,0 +1,97 @@
+# Deprecated
+
+> [!WARNING]
+> The classes described in this document are deprecated and will be removed in a future version.
+
+## General usage
+
+The package provides `DataResponseFactory` class that, given a [PSR-17](https://www.php-fig.org/psr/psr-17/)
+response factory, is able to create data response.
+
+Data response contains raw data to be processed later.
+
+```php
+use Yiisoft\DataResponse\DataResponseFactory;
+
+/**
+ * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
+ */
+
+$factory = new DataResponseFactory($responseFactory);
+$dataResponse = $factory->createResponse('test');
+$dataResponse
+    ->getBody()
+    ->rewind();
+
+echo $dataResponse
+    ->getBody()
+    ->getContents(); // "test"
+```
+
+## Formatters
+
+Formatter purpose is to format a data response. In the following example we format data as JSON.
+
+```php
+use Yiisoft\DataResponse\DataResponseFactory;
+use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
+
+/**
+ * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
+ */
+
+$factory = new DataResponseFactory($responseFactory);
+$dataResponse = $factory->createResponse('test');
+$dataResponse = $dataResponse->withResponseFormatter(new JsonDataResponseFormatter());
+$dataResponse
+    ->getBody()
+    ->rewind();
+
+echo $dataResponse->getHeader('Content-Type'); // ["application/json; charset=UTF-8"]
+echo $dataResponse
+    ->getBody()
+    ->getContents(); // "test"
+```
+
+The following formatters are available:
+
+- `HtmlDataResponseFormatter`
+- `JsonDataResponseFormatter`
+- `XmlDataResponseFormatter`
+- `PlainTextDataResponseFormatter`
+
+## Middleware
+
+The package provides a [PSR-15](https://www.php-fig.org/psr/psr-15/) middleware that is able to format a data response.
+
+```php
+use Yiisoft\DataResponse\Middleware\FormatDataResponse;
+use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
+
+$middleware = (new FormatDataResponse(new JsonDataResponseFormatter()));
+//$middleware->process($request, $handler);
+```
+
+Also, the package provides [PSR-15](https://www.php-fig.org/psr/psr-15/) middleware for content negotiation:
+
+```php
+use Yiisoft\DataResponse\Formatter\HtmlDataResponseFormatter;
+use Yiisoft\DataResponse\Formatter\XmlDataResponseFormatter;
+use Yiisoft\DataResponse\Formatter\JsonDataResponseFormatter;
+use Yiisoft\DataResponse\Middleware\ContentNegotiator;
+
+$middleware = new ContentNegotiator([
+    'text/html' => new HtmlDataResponseFormatter(),
+    'application/xml' => new XmlDataResponseFormatter(),
+    'application/json' => new JsonDataResponseFormatter(),
+]);
+```
+
+You can override middlewares with method `withContentFormatters()`:
+
+```php
+$middleware->withContentFormatters([
+    'application/xml' => new XmlDataResponseFormatter(),
+    'application/json' => new JsonDataResponseFormatter(),
+]);
+```