feat: allow restricting operations for parameter attributes on properties

src/Metadata/HeaderParameter.php

@@ -13,7 +13,7 @@
 
 namespace ApiPlatform\Metadata;
 
-#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE | \Attribute::TARGET_PROPERTY)]
 class HeaderParameter extends Parameter implements HeaderParameterInterface
 {
 }

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/QueryParameter.php

@@ -13,7 +13,7 @@
 
 namespace ApiPlatform\Metadata;
 
-#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE | \Attribute::TARGET_PROPERTY)]
 class QueryParameter extends Parameter implements QueryParameterInterface
 {
 }

src/Metadata/Resource/Factory/ParameterResourceMetadataCollectionFactory.php

@@ -234,6 +234,10 @@ private function getDefaultParameters(Operation $operation, string $resourceClas
         $propertyNames = $properties = [];
         $parameters = $operation->getParameters() ?? new Parameters();
 
+        foreach ($this->createParametersFromAttributes($operation) as $key => $parameter) {
+            $parameters->add($key, $parameter);
+        }
+
         // First loop we look for the :property placeholder and replace its key
         foreach ($parameters as $key => $parameter) {
             if (!str_contains($key, ':property')) {
@@ -469,4 +473,49 @@ private function getFilterInstance(object|string|null $filter): ?object
 
         return $this->filterLocator->get($filter);
     }
+
+    private function createParametersFromAttributes(Operation $operation): Parameters
+    {
+        $parameters = new Parameters();
+
+        if (null === $resourceClass = $operation->getClass()) {
+            return $parameters;
+        }
+
+        foreach ((new \ReflectionClass($resourceClass))->getProperties() as $reflectionProperty) {
+            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;
+
+                if (null === $parameterPropertyName = $parameter->getProperty()) {
+                    $parameter = $parameter->withProperty($propertyName);
+                } elseif ($parameterPropertyName !== $propertyName) {
+                    throw new RuntimeException(\sprintf('Parameter attribute on property "%s" must target itself or have no explicit property. Got "property: \'%s\'" instead.', $propertyName, $parameterPropertyName));
+                }
+
+                if (null === ($parameterProperties = $parameter->getProperties()) || \in_array($propertyName, $parameterProperties, true)) {
+                    $parameter = $parameter->withProperties([$propertyName]);
+                } elseif (!\in_array($propertyName, $parameterProperties, true)) {
+                    throw new RuntimeException(\sprintf('Parameter attribute on property "%s" must target itself or have no explicit properties. Got "properties: [%s]" instead.', $propertyName, implode(', ', $parameterProperties)));
+                }
+
+                $parameters->add($key, $parameter);
+            }
+        }
+
+        return $parameters;
+    }
 }