refactor(metadata): provide a trait in addition to the attribute (#6558)

Co-authored-by: Kévin Dunglas <[email protected]>

- provides an IsApiResource trait that can be used in place of the #[ApiResource] attribute
- enables #[ApiProperty(property: 'foo')] on a class

Author: soyuka

src/Metadata/ApiProperty.php

@@ -202,13 +202,27 @@ public function __construct(
         private $iris = null,
         private ?bool $genId = null,
         private ?string $uriTemplate = null,
+        private ?string $property = null,
         private array $extraProperties = [],
     ) {
         if (\is_string($types)) {
             $this->types = (array) $types;
         }
     }
 
+    public function getProperty(): ?string
+    {
+        return $this->property;
+    }
+
+    public function withProperty(string $property): self
+    {
+        $self = clone $this;
+        $self->property = $property;
+
+        return $self;
+    }
+
     public function getDescription(): ?string
     {
         return $this->description;

src/Metadata/ApiResource.php

@@ -22,7 +22,7 @@
  *
  * The API Resource attribute declares the behaviors attached to a Resource inside API Platform.
  * This class is immutable, and if you set a value yourself, API Platform will not override the value.
- * The API Resource helps sharing options with operations.
+ * The API Resource helps to share options with operations.
  *
  * Read more about how metadata works [here](/docs/in-depth/metadata).
  *

src/Metadata/Extractor/XmlPropertyExtractor.php

@@ -73,6 +73,7 @@ protected function extractPath(string $path): void
                 'iris' => $this->buildArrayValue($property, 'iri'),
                 'genId' => $this->phpize($property, 'genId', 'bool'),
                 'uriTemplate' => $this->phpize($property, 'uriTemplate', 'string'),
+                'property' => $this->phpize($property, 'property', 'string'),
             ];
         }
     }

src/Metadata/Extractor/YamlPropertyExtractor.php

@@ -94,6 +94,7 @@ private function buildProperties(array $resourcesYaml): void
                     'schema' => $this->buildAttribute($propertyValues, 'schema'),
                     'genId' => $this->phpize($propertyValues, 'genId', 'bool'),
                     'uriTemplate' => $this->phpize($propertyValues, 'uriTemplate', 'string'),
+                    'property' => $this->phpize($propertyValues, 'property', 'string'),
                 ];
             }
         }

src/Metadata/Extractor/schema/properties.xsd

@@ -44,6 +44,7 @@
         <xsd:attribute name="securityPostDenormalize" type="xsd:string"/>
         <xsd:attribute name="initializable" type="xsd:boolean"/>
         <xsd:attribute name="genId" type="xsd:boolean"/>
+        <xsd:attribute name="property" type="xsd:string"/>
         <xsd:attribute name="uriTemplate" type="xsd:string"/>
     </xsd:complexType>
 

src/Metadata/IsApiResource.php

@@ -0,0 +1,25 @@
+<?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\Metadata;
+
+/**
+ * @author Kévin Dunglas <[email protected]>
+ */
+trait IsApiResource
+{
+    public static function apiResource(): ApiResource
+    {
+        return new ApiResource();
+    }
+}

src/Metadata/Property/Factory/AttributePropertyMetadataFactory.php

@@ -89,6 +89,14 @@ public function create(string $resourceClass, string $property, array $options =
             }
         }
 
+        $attributes = $reflectionClass->getAttributes(ApiProperty::class);
+        foreach ($attributes as $attribute) {
+            $instance = $attribute->newInstance();
+            if ($instance->getProperty() === $property) {
+                return $this->createMetadata($instance, $parentPropertyMetadata);
+            }
+        }
+
         return $this->handleNotFound($parentPropertyMetadata, $resourceClass, $property);
     }
 

src/Metadata/Property/Factory/ClassLevelAttributePropertyNameCollectionFactory.php

@@ -0,0 +1,49 @@
+<?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\Metadata\Property\Factory;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\Property\PropertyNameCollection;
+
+/**
+ * Gathers "virtual" properties created using the ApiProperty attribute at class level.
+ */
+final class ClassLevelAttributePropertyNameCollectionFactory implements PropertyNameCollectionFactoryInterface
+{
+    public function __construct(
+        private readonly ?PropertyNameCollectionFactoryInterface $decorated = null,
+    ) {
+    }
+
+    public function create(string $resourceClass, array $options = []): PropertyNameCollection
+    {
+        $parentPropertyNameCollection = $this->decorated?->create($resourceClass, $options);
+        if (!class_exists($resourceClass)) {
+            return $parentPropertyNameCollection ?? new PropertyNameCollection();
+        }
+
+        $properties = $parentPropertyNameCollection ? iterator_to_array($parentPropertyNameCollection) : [];
+
+        $refl = new \ReflectionClass($resourceClass);
+        $attributes = $refl->getAttributes(ApiProperty::class);
+        foreach ($attributes as $attribute) {
+            $instance = $attribute->newInstance();
+            if ($property = $instance->getProperty()) {
+                $properties[] = $property;
+            }
+        }
+
+        return new PropertyNameCollection($properties);
+    }
+}

src/Metadata/Property/Factory/ConcernsPropertyNameCollectionMetadataFactory.php

@@ -0,0 +1,69 @@
+<?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\Metadata\Property\Factory;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\IsApiResource;
+use ApiPlatform\Metadata\Property\PropertyNameCollection;
+
+/**
+ * Handles property defined with the {@see IsApiResource} concern.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+final class ConcernsPropertyNameCollectionMetadataFactory implements PropertyNameCollectionFactoryInterface
+{
+    public function __construct(
+        private readonly ?PropertyNameCollectionFactoryInterface $decorated = null,
+    ) {
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @param class-string $resourceClass
+     */
+    public function create(string $resourceClass, array $options = []): PropertyNameCollection
+    {
+        $propertyNameCollection = $this->decorated?->create($resourceClass, $options);
+        if (!method_exists($resourceClass, 'apiResource')) {
+            return $propertyNameCollection ?? new PropertyNameCollection();
+        }
+
+        $refl = new \ReflectionClass($resourceClass);
+        $method = $refl->getMethod('apiResource');
+        if (!$method->isPublic() || !$method->isStatic()) {
+            return $propertyNameCollection ?? new PropertyNameCollection();
+        }
+
+        $metadataCollection = $method->invoke(null);
+        if (!\is_array($metadataCollection)) {
+            $metadataCollection = [$metadataCollection];
+        }
+
+        $properties = $propertyNameCollection ? array_flip(iterator_to_array($propertyNameCollection)) : [];
+
+        foreach ($metadataCollection as $apiProperty) {
+            if (!$apiProperty instanceof ApiProperty) {
+                continue;
+            }
+
+            if (null !== $propertyName = $apiProperty->getProperty()) {
+                $properties[$propertyName] = true;
+            }
+        }
+
+        return new PropertyNameCollection(array_keys($properties));
+    }
+}