fix(metadata): _format broken bc promise on #5080

Author: soyuka

src/Metadata/Resource/Factory/UriTemplateResourceMetadataCollectionFactory.php

@@ -27,6 +27,8 @@
  */
 final class UriTemplateResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
 {
+    private $triggerLegacyFormatOnce = [];
+
     public function __construct(private readonly LinkFactoryInterface $linkFactory, private readonly PathSegmentNameGeneratorInterface $pathSegmentNameGenerator, private readonly ?ResourceMetadataCollectionFactoryInterface $decorated = null)
     {
     }
@@ -96,6 +98,15 @@ private function generateUriTemplate(HttpOperation $operation): string
         $uriTemplate = $operation->getUriTemplate() ?? sprintf('/%s', $this->pathSegmentNameGenerator->getSegmentName($operation->getShortName()));
         $uriVariables = $operation->getUriVariables() ?? [];
 
+        if (str_ends_with($uriTemplate, '{._format}') || ($legacyFormat = str_ends_with($uriTemplate, '.{_format}'))) {
+            $uriTemplate = substr($uriTemplate, 0, -10);
+        }
+
+        if ($legacyFormat && ($this->triggerLegacyFormatOnce[$operation->getClass()] ?? true)) {
+            $this->triggerLegacyFormatOnce[$operation->getClass()] = false;
+            trigger_deprecation('api-platform/core', '3.0', sprintf('The special Symfony parameter ".{_format}" in your URI Template is deprecated, use an RFC6570 variable "{._format}" on the class "%s" instead. We will only use the RFC6570 compatible variable in 4.0.', $operation->getClass()));
+        }
+
         if ($parameters = array_keys($uriVariables)) {
             foreach ($parameters as $parameterName) {
                 $part = sprintf('/{%s}', $parameterName);
@@ -105,7 +116,7 @@ private function generateUriTemplate(HttpOperation $operation): string
             }
         }
 
-        return sprintf('%s{._format}', $uriTemplate);
+        return sprintf('%s%s', $uriTemplate, $legacyFormat ? '.{_format}' : '{._format}');
     }
 
     private function configureUriVariables(ApiResource|HttpOperation $operation): ApiResource|HttpOperation
@@ -144,7 +155,7 @@ private function configureUriVariables(ApiResource|HttpOperation $operation): Ap
         }
         $operation = $operation->withUriVariables($uriVariables);
 
-        if (str_ends_with($uriTemplate, '{._format}')) {
+        if (str_ends_with($uriTemplate, '{._format}') || str_ends_with($uriTemplate, '.{_format}')) {
             $uriTemplate = substr($uriTemplate, 0, -10);
         }
 

tests/Fixtures/TestBundle/ApiResourceNotLoaded/SymfonyFormatParameterLegacy.php

@@ -0,0 +1,21 @@
+<?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\Tests\Fixtures\TestBundle\ApiResourceNotLoaded;
+
+use ApiPlatform\Metadata\ApiResource;
+
+#[ApiResource('/format_not_rfc.{_format}')]
+class SymfonyFormatParameterLegacy
+{
+}

tests/Metadata/Resource/Factory/UriTemplateResourceMetadataCollectionFactoryTest.php

@@ -23,22 +23,26 @@
 use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\Property\PropertyNameCollection;
 use ApiPlatform\Metadata\Put;
+use ApiPlatform\Metadata\Resource\Factory\AttributesResourceMetadataCollectionFactory;
 use ApiPlatform\Metadata\Resource\Factory\LinkFactory;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\Resource\Factory\UriTemplateResourceMetadataCollectionFactory;
 use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
 use ApiPlatform\Operation\PathSegmentNameGeneratorInterface;
+use ApiPlatform\Tests\Fixtures\TestBundle\ApiResourceNotLoaded\SymfonyFormatParameterLegacy;
 use ApiPlatform\Tests\Fixtures\TestBundle\Entity\AttributeResource;
 use ApiPlatform\Tests\Fixtures\TestBundle\Entity\Dummy;
 use PHPUnit\Framework\TestCase;
 use Prophecy\Argument;
 use Prophecy\PhpUnit\ProphecyTrait;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 
 /**
  * @author Antoine Bluchet <[email protected]>
  */
 class UriTemplateResourceMetadataCollectionFactoryTest extends TestCase
 {
+    use ExpectDeprecationTrait;
     use ProphecyTrait;
 
     public function testCreate(): void
@@ -169,4 +173,25 @@ class: AttributeResource::class,
             $uriTemplateResourceMetadataCollectionFactory->create(AttributeResource::class)
         );
     }
+
+    /**
+     * @group legacy
+     */
+    public function testCreateWithLegacyFormat(): void
+    {
+        $this->expectDeprecation('Since api-platform/core 3.0: The special Symfony parameter ".{_format}" in your URI Template is deprecated, use an RFC6570 variable "{._format}" on the class "ApiPlatform\Tests\Fixtures\TestBundle\ApiResourceNotLoaded\SymfonyFormatParameterLegacy" instead. We will only use the RFC6570 compatible variable in 4.0.');
+
+        $propertyNameCollectionFactoryProphecy = $this->prophesize(PropertyNameCollectionFactoryInterface::class);
+        $propertyNameCollectionFactoryProphecy->create(Argument::cetera())->willReturn(new PropertyNameCollection());
+        $propertyMetadataFactoryProphecy = $this->prophesize(PropertyMetadataFactoryInterface::class);
+        $resourceClassResolverProphecy = $this->prophesize(ResourceClassResolverInterface::class);
+        $linkFactory = new LinkFactory($propertyNameCollectionFactoryProphecy->reveal(), $propertyMetadataFactoryProphecy->reveal(), $resourceClassResolverProphecy->reveal());
+        $pathSegmentNameGeneratorProphecy = $this->prophesize(PathSegmentNameGeneratorInterface::class);
+        $pathSegmentNameGeneratorProphecy->getSegmentName('SymfonyFormatParameterLegacy')->willReturn('attribute_resources');
+        $resourceCollectionMetadataFactoryProphecy = new AttributesResourceMetadataCollectionFactory();
+
+        $linkFactory = new LinkFactory($propertyNameCollectionFactoryProphecy->reveal(), $propertyMetadataFactoryProphecy->reveal(), $resourceClassResolverProphecy->reveal());
+        $uriTemplateResourceMetadataCollectionFactory = new UriTemplateResourceMetadataCollectionFactory($linkFactory, $pathSegmentNameGeneratorProphecy->reveal(), $resourceCollectionMetadataFactoryProphecy);
+        $uriTemplateResourceMetadataCollectionFactory->create(SymfonyFormatParameterLegacy::class);
+    }
 }