feat: allow restricting operations for parameter attributes on properties

Author: Maxcastel

src/Metadata/Parameter.php

@@ -42,6 +42,7 @@ abstract class Parameter
      * @param ?bool                                           $castToNativeType whether API Platform should cast your parameter to the nativeType declared
      * @param ?callable(mixed): mixed                         $castFn           the closure used to cast your parameter, this gets called only when $castToNativeType is set
      * @param ?string                                         $filterClass      the class to use when resolving filter properties (from stateOptions)
+     * @param list<Operation>|null                            $operations       a list of operations this parameter applies to (if null, applies to all operations)
      *
      * @phpstan-param array<string, mixed>|null $schema
      *
@@ -70,6 +71,7 @@ public function __construct(
         protected mixed $castFn = null,
         protected mixed $default = null,
         protected ?string $filterClass = null,
+        protected ?array $operations = null,
     ) {
     }
 
@@ -410,4 +412,23 @@ public function withFilterClass(?string $filterClass): self
 
         return $self;
     }
+
+    /**
+     * @return list<Operation>|null
+     */
+    public function getOperations(): ?array
+    {
+        return $this->operations;
+    }
+
+    /**
+     * @param list<Operation>|null $operations
+     */
+    public function withOperations(?array $operations): self
+    {
+        $self = clone $this;
+        $self->operations = $operations;
+
+        return $self;
+    }
 }

src/Metadata/Resource/Factory/ParameterResourceMetadataCollectionFactory.php

@@ -486,6 +486,17 @@ private function createParametersFromAttributes(Operation $operation): Parameter
             foreach ($reflectionProperty->getAttributes(Parameter::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
                 $parameter = $attribute->newInstance();
 
+                if (
+                    null !== ($parameterOperations = $parameter->getOperations())
+                    && !\in_array(
+                        $operation::class,
+                        array_map(static fn ($parameterOperation) => $parameterOperation::class, $parameterOperations),
+                        true
+                    )
+                ) {
+                    continue;
+                }
+
                 $propertyName = $reflectionProperty->getName();
                 $key = $parameter->getKey() ?? $propertyName;
 

src/Metadata/Tests/Resource/Factory/ParameterResourceMetadataCollectionFactoryTest.php

@@ -17,6 +17,7 @@
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\Exception\RuntimeException;
 use ApiPlatform\Metadata\FilterInterface;
+use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\HeaderParameter;
 use ApiPlatform\Metadata\Parameters;
@@ -658,6 +659,78 @@ public function testHeaderParameterFromPropertyAttributePropertiesHasMultipleInc
         $this->assertSame(['authToken'], $authParam->getProperties());
     }
 
+    public function testQueryParameterOnPropertiesWithOperations(): void
+    {
+        $nameCollection = $this->createStub(PropertyNameCollectionFactoryInterface::class);
+        $nameCollection->method('create')->willReturn(new PropertyNameCollection(['id', 'name']));
+
+        $propertyMetadata = $this->createStub(PropertyMetadataFactoryInterface::class);
+        $propertyMetadata->method('create')->willReturn(
+            new ApiProperty(readable: true),
+        );
+
+        $filterLocator = $this->createStub(ContainerInterface::class);
+        $filterLocator->method('has')->willReturn(false);
+
+        $parameterFactory = new ParameterResourceMetadataCollectionFactory(
+            $nameCollection,
+            $propertyMetadata,
+            new AttributesResourceMetadataCollectionFactory(),
+            $filterLocator
+        );
+
+        $resourceMetadataCollection = $parameterFactory->create(QueryParameterOnPropertiesWithOperations::class);
+        $operations = array_values(iterator_to_array($resourceMetadataCollection[0]->getOperations()));
+
+        $collectionOperation = $operations[0];
+        $this->assertInstanceOf(GetCollection::class, $collectionOperation);
+        $collectionParameters = $collectionOperation->getParameters();
+        $this->assertTrue($collectionParameters->has('search'));
+        $this->assertFalse($collectionParameters->has('filter_id'));
+
+        $getOperation = $operations[1];
+        $this->assertInstanceOf(Get::class, $getOperation);
+        $getParameters = $getOperation->getParameters();
+        $this->assertTrue($getParameters->has('search'));
+        $this->assertTrue($getParameters->has('filter_id'));
+    }
+
+    public function testHeaderParameterOnPropertiesWithOperations(): void
+    {
+        $nameCollection = $this->createStub(PropertyNameCollectionFactoryInterface::class);
+        $nameCollection->method('create')->willReturn(new PropertyNameCollection(['id', 'authToken', 'apiKey']));
+
+        $propertyMetadata = $this->createStub(PropertyMetadataFactoryInterface::class);
+        $propertyMetadata->method('create')->willReturn(
+            new ApiProperty(readable: true),
+        );
+
+        $filterLocator = $this->createStub(ContainerInterface::class);
+        $filterLocator->method('has')->willReturn(false);
+
+        $parameterFactory = new ParameterResourceMetadataCollectionFactory(
+            $nameCollection,
+            $propertyMetadata,
+            new AttributesResourceMetadataCollectionFactory(),
+            $filterLocator
+        );
+
+        $resourceMetadataCollection = $parameterFactory->create(HeaderParameterOnPropertiesWithOperations::class);
+        $operations = array_values(iterator_to_array($resourceMetadataCollection[0]->getOperations()));
+
+        $collectionOperation = $operations[0];
+        $this->assertInstanceOf(GetCollection::class, $collectionOperation);
+        $collectionParameters = $collectionOperation->getParameters();
+        $this->assertFalse($collectionParameters->has('X-Authorization', HeaderParameter::class));
+        $this->assertTrue($collectionParameters->has('X-API-Key', HeaderParameter::class));
+
+        $getOperation = $operations[1];
+        $this->assertInstanceOf(Get::class, $getOperation);
+        $getParameters = $getOperation->getParameters();
+        $this->assertTrue($getParameters->has('X-Authorization', HeaderParameter::class));
+        $this->assertTrue($getParameters->has('X-API-Key', HeaderParameter::class));
+    }
+
     public function testNestedPropertyWithNameConverter(): void
     {
         $nameCollection = $this->createStub(PropertyNameCollectionFactoryInterface::class);
@@ -1027,3 +1100,33 @@ class HeaderParameterOnPropertiesMismatchMultiplePropertiesException
 
     public string $token2 = '';
 }
+
+#[ApiResource(
+    operations: [
+        new GetCollection(),
+        new Get(),
+    ]
+)]
+class QueryParameterOnPropertiesWithOperations
+{
+    #[QueryParameter(key: 'search', description: 'Search by name', operations: [new GetCollection(), new Get()])]
+    public string $name = '';
+
+    #[QueryParameter(key: 'filter_id', description: 'Filter by ID', operations: [new Get()])]
+    public int $id = 0;
+}
+
+#[ApiResource(
+    operations: [
+        new GetCollection(),
+        new Get(),
+    ]
+)]
+class HeaderParameterOnPropertiesWithOperations
+{
+    #[HeaderParameter(key: 'X-Authorization', description: 'Authorization header', operations: [new Get()])]
+    public string $authToken = '';
+
+    #[HeaderParameter(key: 'X-API-Key', description: 'API key header', operations: [new GetCollection(), new Get()])]
+    public string $apiKey = '';
+}