feat: deprecate not setting formats manually (#5808)

introduces documentation formats

Co-authored-by: Sarahshr <[email protected]>

Tests/YamlEncoderTest.php

@@ -0,0 +1,58 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Serializer\Tests;
+
+use ApiPlatform\Serializer\YamlEncoder;
+use PHPUnit\Framework\TestCase;
+
+class YamlEncoderTest extends TestCase
+{
+    private YamlEncoder $encoder;
+
+    protected function setUp(): void
+    {
+        $this->encoder = new YamlEncoder('yamlopenapi');
+    }
+
+    public function testSupportEncoding(): void
+    {
+        $this->assertTrue($this->encoder->supportsEncoding('yamlopenapi'));
+        $this->assertFalse($this->encoder->supportsEncoding('json'));
+    }
+
+    public function testEncode(): void
+    {
+        $data = ['foo' => 'bar'];
+
+        $this->assertSame('{ foo: bar }', $this->encoder->encode($data, 'yamlopenapi'));
+    }
+
+    public function testSupportDecoding(): void
+    {
+        $this->assertTrue($this->encoder->supportsDecoding('yamlopenapi'));
+        $this->assertFalse($this->encoder->supportsDecoding('json'));
+    }
+
+    public function testDecode(): void
+    {
+        $this->assertEquals(['foo' => 'bar'], $this->encoder->decode('{ foo: bar }', 'yamlopenapi'));
+    }
+
+    public function testUTF8EncodedString(): void
+    {
+        $data = ['foo' => 'Über'];
+
+        $this->assertEquals('{ foo: Über }', $this->encoder->encode($data, 'yamlopenapi'));
+    }
+}

YamlEncoder.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Serializer;
+
+use Symfony\Component\Serializer\Encoder\DecoderInterface;
+use Symfony\Component\Serializer\Encoder\EncoderInterface;
+use Symfony\Component\Serializer\Encoder\YamlEncoder as BaseYamlEncoder;
+
+/**
+ * A YAML encoder with appropriate default options to embed the generated document into HTML.
+ */
+final class YamlEncoder implements EncoderInterface, DecoderInterface
+{
+    public function __construct(private readonly string $format = 'yamlopenapi', private readonly EncoderInterface&DecoderInterface $yamlEncoder = new BaseYamlEncoder())
+    {
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsEncoding($format, array $context = []): bool
+    {
+        return $this->format === $format;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function encode($data, $format, array $context = []): string
+    {
+        return $this->yamlEncoder->encode($data, $format, $context);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsDecoding($format, array $context = []): bool
+    {
+        return $this->format === $format;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function decode($data, $format, array $context = []): mixed
+    {
+        return $this->yamlEncoder->decode($data, $format, $context);
+    }
+}

composer.json

@@ -30,10 +30,11 @@
         "symfony/validator": "^6.3"
     },
     "require-dev": {
+        "api-platform/symfony": "*@dev || ^3.1",
         "phpspec/prophecy-phpunit": "^2.0",
-        "symfony/phpunit-bridge": "^6.1",
         "symfony/mercure-bundle": "*",
-        "api-platform/symfony": "*@dev || ^3.1"
+        "symfony/phpunit-bridge": "^6.1",
+        "symfony/yaml": "^6.3"
     },
     "autoload": {
         "psr-4": {