Add PlainTextDataResponseFormatter and FormatDataResponseAsPlainText

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Enh #85: Raise minimum PHP version to 8.1 and refactor code (@vjik)
 - Enh #80: Add support for `psr/http-message` version `^2.0` (@vjik)
 - Bug #85: Explicitly add transitive dependencies `psr/http-factory` and `psr/http-server-handler` (@vjik)
+- New #88: Add `PlainTextDataResponseFormatter` formatter and `FormatDataResponseAsPlainText` middleware (@vjik) 
 
 ## 2.0.0 February 15, 2023
 

README.md

@@ -27,7 +27,7 @@ response.
 The package could be installed via composer:
 
 ```shell
-composer require yiisoft/data-response --prefer-dist
+composer require yiisoft/data-response
 ```
 
 ## General usage
@@ -85,6 +85,7 @@ The following formatters are available:
 - `HtmlDataResponseFormatter`
 - `JsonDataResponseFormatter`
 - `XmlDataResponseFormatter`
+- `PlainTextDataResponseFormatter`
 
 ### Middleware
 

src/Formatter/PlainTextDataResponseFormatter.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\DataResponse\Formatter;
+
+use LogicException;
+use Psr\Http\Message\ResponseInterface;
+use Stringable;
+use Yiisoft\DataResponse\DataResponse;
+use Yiisoft\DataResponse\DataResponseFormatterInterface;
+use Yiisoft\DataResponse\ResponseContentTrait;
+
+/**
+ * `PlainTextDataResponseFormatter` formats the response data as plain text.
+ */
+final class PlainTextDataResponseFormatter implements DataResponseFormatterInterface
+{
+    use ResponseContentTrait;
+
+    /**
+     * @var string The Content-Type header for the response.
+     */
+    private string $contentType = 'text/plain';
+
+    /**
+     * @var string The encoding for the Content-Type header.
+     */
+    private string $encoding = 'UTF-8';
+
+    /**
+     * @inheritDoc
+     */
+    public function format(DataResponse $dataResponse): ResponseInterface
+    {
+        $data = $dataResponse->getData();
+
+        if (!is_scalar($data) && $data !== null && !$data instanceof Stringable) {
+            throw new LogicException(sprintf(
+                'Data must be either a scalar value, null, or a stringable object. %s given.',
+                get_debug_type($data),
+            ));
+        }
+
+        return $this->addToResponse($dataResponse->getResponse(), empty($data) ? null : (string) $data);
+    }
+}

src/Middleware/FormatDataResponseAsPlainText.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\DataResponse\Middleware;
+
+use Yiisoft\DataResponse\Formatter\PlainTextDataResponseFormatter;
+
+/**
+ * `FormatDataResponseAsPlainText` adds a plain text formatter {@see PlainTextDataResponseFormatter} instance to the
+ * instance of the data response {@see DataResponse}, if the formatter was not added earlier.
+ */
+final class FormatDataResponseAsPlainText extends FormatDataResponse
+{
+    public function __construct(PlainTextDataResponseFormatter $responseFormatter)
+    {
+        parent::__construct($responseFormatter);
+    }
+}

tests/Formatter/PlainTextDataResponseFormatterTest.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\DataResponse\Tests\Formatter;
+
+use LogicException;
+use Yiisoft\DataResponse\Formatter\PlainTextDataResponseFormatter;
+use Yiisoft\DataResponse\Tests\TestCase;
+
+final class PlainTextDataResponseFormatterTest extends TestCase
+{
+    public function testCorrectFormat(): void
+    {
+        $dataResponse = $this->createDataResponse('test');
+        $result = (new PlainTextDataResponseFormatter())->format($dataResponse);
+        $result->getBody()->rewind();
+
+        $this->assertSame(
+            'test',
+            $result->getBody()->getContents(),
+        );
+        $this->assertSame(['text/plain; charset=UTF-8'], $result->getHeader('Content-Type'));
+    }
+
+    public function testWithEncoding(): void
+    {
+        $dataResponse = $this->createDataResponse('test');
+        $result = (new PlainTextDataResponseFormatter())
+            ->withEncoding('ISO-8859-1')
+            ->format($dataResponse);
+        $result->getBody()->rewind();
+
+        $this->assertSame(
+            'test',
+            $result->getBody()->getContents(),
+        );
+        $this->assertSame(['text/plain; charset=ISO-8859-1'], $result->getHeader('Content-Type'));
+    }
+
+    public function testWithContentType(): void
+    {
+        $dataResponse = $this->createDataResponse('test');
+        $result = (new PlainTextDataResponseFormatter())
+            ->withContentType('text/html')
+            ->format($dataResponse);
+        $result->getBody()->rewind();
+
+        $this->assertSame(
+            'test',
+            $result->getBody()->getContents(),
+        );
+        $this->assertSame('text/html; charset=UTF-8', $result->getHeaderLine('Content-Type'));
+    }
+
+    public function testWithIncorrectType(): void
+    {
+        $dataResponse = $this->createDataResponse(['test']);
+        $formatter = new PlainTextDataResponseFormatter();
+
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('Data must be either a scalar value, null, or a stringable object. array given.');
+        $formatter->format($dataResponse);
+    }
+
+    public function testDataWithNull(): void
+    {
+        $dataResponse = $this->createDataResponse(null);
+        $result = (new PlainTextDataResponseFormatter())->format($dataResponse);
+        $result->getBody()->rewind();
+
+        $this->assertSame(
+            '',
+            $result->getBody()->getContents(),
+        );
+        $this->assertSame(['text/plain; charset=UTF-8'], $result->getHeader('Content-Type'));
+    }
+
+    public function testDataWithStringableObject(): void
+    {
+        $data = new class () {
+            public function __toString(): string
+            {
+                return 'test';
+            }
+        };
+
+        $dataResponse = $this->createDataResponse($data);
+        $result = (new PlainTextDataResponseFormatter())->format($dataResponse);
+        $result->getBody()->rewind();
+
+        $this->assertSame(
+            'test',
+            $result->getBody()->getContents(),
+        );
+        $this->assertSame(['text/plain; charset=UTF-8'], $result->getHeader('Content-Type'));
+    }
+
+    public function testImmutability(): void
+    {
+        $formatter = new PlainTextDataResponseFormatter();
+        $this->assertNotSame($formatter, $formatter->withContentType('text/html'));
+        $this->assertNotSame($formatter, $formatter->withEncoding('utf-8'));
+    }
+}

tests/Middleware/FormatDataResponseAsPlainTextTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\DataResponse\Tests\Middleware;
+
+use Yiisoft\DataResponse\Formatter\PlainTextDataResponseFormatter;
+use Yiisoft\DataResponse\Middleware\FormatDataResponseAsPlainText;
+use Yiisoft\DataResponse\Tests\TestCase;
+
+final class FormatDataResponseAsPlainTextTest extends TestCase
+{
+    public function testBase(): void
+    {
+        $middleware = new FormatDataResponseAsPlainText(new PlainTextDataResponseFormatter());
+        $dataResponse = $this->createDataResponse('test');
+
+        $response = $middleware->process(
+            $this->createRequest(),
+            $this->createRequestHandler($dataResponse)
+        );
+
+        $response->getBody()->rewind();
+
+        $this->assertSame('test', $response->getBody()->getContents());
+        $this->assertSame(['text/plain; charset=UTF-8'], $response->getHeader('Content-Type'));
+    }
+}