Add ContentTypeAwarePayload and ContentAwareEncoder

Introduce a generic DTO that pairs any payload with a content type,
and a decorator encoder that wraps any existing encoder to set the
Content-Type header from the payload metadata.

Author: veewee

docs/transports.md

@@ -42,6 +42,7 @@ This package contains some frequently used encoders / decoders for you:
 | `RawDecoder`            | `DecoderInterface<string>`            | Returns the raw PSR-7 body string as response result                                |
 | `ResourceStreamEncoder` | `EncoderInterface<ResourceStream>`    | Adds `phpro/resource-stream` as request body                                        |
 | `ResourceStreamDecoder` | `DecoderInterface<ResourceStream>`    | Returns `phpro/resource-stream` from response body                                  |
+| `ContentTypeAwareEncoder`   | `EncoderInterface<ContentTypeAwarePayload<T>>` | Decorator that wraps any encoder and sets the Content-Type header from the payload |
 | `ResponseDecoder`       | `DecoderInterface<ResponseInterface>` | Returns the received PSR-7 response as result                                       |
 
 ## Built-in transport presets:

src/Encoding/ContentType/ContentTypeAwareEncoder.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\HttpTools\Encoding\ContentType;
+
+use Phpro\HttpTools\Encoding\EncoderInterface;
+use Psr\Http\Message\RequestInterface;
+
+/**
+ * @template T
+ *
+ * @implements EncoderInterface<ContentTypeAwarePayload<T>>
+ */
+final class ContentTypeAwareEncoder implements EncoderInterface
+{
+    /**
+     * @param EncoderInterface<T> $encoder
+     */
+    public function __construct(
+        private EncoderInterface $encoder,
+    ) {
+    }
+
+    /**
+     * @param ContentTypeAwarePayload<T> $data
+     */
+    public function __invoke(RequestInterface $request, $data): RequestInterface
+    {
+        $request = ($this->encoder)($request, $data->payload);
+
+        return $request->withHeader('Content-Type', $data->contentType);
+    }
+}

src/Encoding/ContentType/ContentTypeAwarePayload.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\HttpTools\Encoding\ContentType;
+
+/**
+ * @template T
+ */
+final readonly class ContentTypeAwarePayload
+{
+    /**
+     * @param T $payload
+     */
+    public function __construct(
+        public string $contentType,
+        public mixed $payload,
+    ) {
+    }
+}

tests/Unit/Encoding/ContentType/ContentTypeAwareEncoderTest.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\HttpTools\Tests\Unit\Encoding\ContentType;
+
+use Phpro\HttpTools\Encoding\ContentType\ContentTypeAwareEncoder;
+use Phpro\HttpTools\Encoding\ContentType\ContentTypeAwarePayload;
+use Phpro\HttpTools\Encoding\Raw\RawEncoder;
+use Phpro\HttpTools\Test\UseHttpFactories;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class ContentTypeAwareEncoderTest extends TestCase
+{
+    use UseHttpFactories;
+
+    #[Test]
+    public function it_can_encode_with_content_type(): void
+    {
+        $encoder = new ContentTypeAwareEncoder(
+            RawEncoder::createWithAutodiscoveredPsrFactories()
+        );
+        $request = $this->createRequest('POST', '/hello');
+        $payload = new ContentTypeAwarePayload('application/pdf', 'raw-content');
+
+        $actual = $encoder($request, $payload);
+
+        self::assertSame('raw-content', (string) $actual->getBody());
+        self::assertSame('application/pdf', $actual->getHeaderLine('Content-Type'));
+    }
+
+    #[Test]
+    public function it_overrides_content_type_set_by_inner_encoder(): void
+    {
+        $encoder = new ContentTypeAwareEncoder(
+            RawEncoder::createWithAutodiscoveredPsrFactories()
+        );
+        $request = $this->createRequest('POST', '/hello')
+            ->withHeader('Content-Type', 'text/plain');
+        $payload = new ContentTypeAwarePayload('application/xml', 'raw-content');
+
+        $actual = $encoder($request, $payload);
+
+        self::assertSame('application/xml', $actual->getHeaderLine('Content-Type'));
+    }
+}