feat(metadata): use PHP file as resource format

src/Metadata/Extractor/PhpFileResourceExtractor.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * 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\Extractor;
+
+use ApiPlatform\Metadata\ApiResource;
+
+/**
+ * Extracts an array of metadata from a list of PHP files.
+ *
+ * @author Loïc Frémont <lc.fremont@gmail.com>
+ */
+final class PhpFileResourceExtractor extends AbstractResourceExtractor
+{
+    use ResourceExtractorTrait;
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function extractPath(string $path): void
+    {
+        $resource = $this->getPHPFileClosure($path)();
+
+        if (!$resource instanceof ApiResource) {
+            return;
+        }
+
+        $resourceReflection = new \ReflectionClass($resource);
+
+        foreach ($resourceReflection->getProperties() as $property) {
+            $property->setAccessible(true);
+            $resolvedValue = $this->resolve($property->getValue($resource));
+            $property->setValue($resource, $resolvedValue);
+        }
+
+        $this->resources = [$resource];
+    }
+
+    /**
+     * Scope isolated include.
+     *
+     * Prevents access to $this/self from included files.
+     */
+    private function getPHPFileClosure(string $filePath): \Closure
+    {
+        return \Closure::bind(function () use ($filePath): mixed {
+            return require $filePath;
+        }, null, null);
+    }
+}

src/Metadata/Resource/Factory/PhpFileResourceMetadataCollectionFactory.php

@@ -0,0 +1,65 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * 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\Resource\Factory;
+
+use ApiPlatform\Metadata\Extractor\ResourceExtractorInterface;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+
+final class PhpFileResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
+{
+    use OperationDefaultsTrait;
+
+    public function __construct(
+        private readonly ResourceExtractorInterface $metadataExtractor,
+        private readonly ?ResourceMetadataCollectionFactoryInterface $decorated = null,
+    ) {
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function create(string $resourceClass): ResourceMetadataCollection
+    {
+        $resourceMetadataCollection = new ResourceMetadataCollection($resourceClass);
+        if ($this->decorated) {
+            $resourceMetadataCollection = $this->decorated->create($resourceClass);
+        }
+
+        foreach ($this->metadataExtractor->getResources() as $resource) {
+            if ($resourceClass !== $resource->getClass()) {
+                continue;
+            }
+
+            $shortName = (false !== $pos = strrpos($resourceClass, '\\')) ? substr($resourceClass, $pos + 1) : $resourceClass;
+            $resource = $this->getResourceWithDefaults($resourceClass, $shortName, $resource);
+
+            $operations = [];
+            /** @var Operation $operation */
+            foreach ($resource->getOperations() ?? new Operations() as $operation) {
+                [$key, $operation] = $this->getOperationWithDefaults($resource, $operation);
+                $operations[$key] = $operation;
+            }
+
+            if ($operations) {
+                $resource = $resource->withOperations(new Operations($operations));
+            }
+
+            $resourceMetadataCollection[] = $resource;
+        }
+
+        return $resourceMetadataCollection;
+    }
+}

src/Metadata/Resource/Factory/PhpFileResourceNameCollectionFactory.php

@@ -0,0 +1,55 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * 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\Resource\Factory;
+
+use ApiPlatform\Metadata\Extractor\ResourceExtractorInterface;
+use ApiPlatform\Metadata\Resource\ResourceNameCollection;
+
+/**
+ * @internal
+ */
+final class PhpFileResourceNameCollectionFactory implements ResourceNameCollectionFactoryInterface
+{
+    public function __construct(
+        private readonly ResourceExtractorInterface $metadataExtractor,
+        private readonly ?ResourceNameCollectionFactoryInterface $decorated = null,
+    ) {
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function create(): ResourceNameCollection
+    {
+        $classes = [];
+
+        if ($this->decorated) {
+            foreach ($this->decorated->create() as $resourceClass) {
+                $classes[$resourceClass] = true;
+            }
+        }
+
+        foreach ($this->metadataExtractor->getResources() as $resource) {
+            $resourceClass = $resource->getClass();
+
+            if (null === $resourceClass) {
+                continue;
+            }
+
+            $classes[$resourceClass] = true;
+        }
+
+        return new ResourceNameCollection(array_keys($classes));
+    }
+}

src/Metadata/Tests/Extractor/PhpFileResourceExtractorTest.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * 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\Tests\Extractor;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Extractor\PhpFileResourceExtractor;
+use PHPUnit\Framework\TestCase;
+
+final class PhpFileResourceExtractorTest extends TestCase
+{
+    public function testItGetsResourcesFromPhpFileThatReturnsAnApiResource(): void
+    {
+        $extractor = new PhpFileResourceExtractor([__DIR__.'/php/valid_php_file.php']);
+
+        $expectedResource = new ApiResource(shortName: 'dummy');
+
+        $this->assertEquals([$expectedResource], $extractor->getResources());
+    }
+
+    public function testItExcludesResourcesFromPhpFileThatDoesNotReturnAnApiResource(): void
+    {
+        $extractor = new PhpFileResourceExtractor([__DIR__.'/php/invalid_php_file.php']);
+
+        $this->assertEquals([], $extractor->getResources());
+    }
+}

src/Metadata/Tests/Extractor/php/invalid_php_file.php

@@ -0,0 +1,14 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+return new stdClass();

src/Metadata/Tests/Extractor/php/valid_php_file.php

@@ -0,0 +1,16 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+use ApiPlatform\Metadata\ApiResource;
+
+return new ApiResource(shortName: 'dummy');

src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

@@ -320,7 +320,7 @@
 
     private function registerMetadataConfiguration(ContainerBuilder $container, array $config, XmlFileLoader $loader): void
     {
-        [$xmlResources, $yamlResources] = $this->getResourcesToWatch($container, $config);
+        [$xmlResources, $yamlResources, $phpResources] = $this->getResourcesToWatch($container, $config);
 
         $container->setParameter('api_platform.class_name_resources', $this->getClassNameResources());
 
@@ -335,6 +335,7 @@
         }
 
         // V3 metadata
+        $loader->load('metadata/php.xml');
         $loader->load('metadata/xml.xml');
         $loader->load('metadata/links.xml');
         $loader->load('metadata/property.xml');
@@ -353,6 +354,8 @@
             $container->getDefinition('api_platform.metadata.resource_extractor.yaml')->replaceArgument(0, $yamlResources);
             $container->getDefinition('api_platform.metadata.property_extractor.yaml')->replaceArgument(0, $yamlResources);
         }
+
+        $container->getDefinition('api_platform.metadata.resource_extractor.php_file')->replaceArgument(0, $phpResources);
     }
 
     private function getClassNameResources(): array
@@ -417,7 +420,32 @@
             }
         }
 
-        $resources = ['yml' => [], 'xml' => [], 'dir' => []];
+        $resources = ['yml' => [], 'xml' => [], 'php' => [], 'dir' => []];
+
+        foreach ($config['mapping']['imports'] ?? [] as $path) {
+            if (is_dir($path)) {
+                foreach (Finder::create()->followLinks()->files()->in($path)->name('/\.php$/')->sortByName() as $file) {
+                    $resources[$file->getExtension()][] = $file->getRealPath();
+                }
+
+                $resources['dir'][] = $path;
+                $container->addResource(new DirectoryResource($path, '/\.php$/'));
+
+                continue;
+            }
+
+            if ($container->fileExists($path, false)) {
+                if (!str_ends_with($path, '.php')) {
+                    throw new RuntimeException(\sprintf('Unsupported mapping type in "%s", supported type is PHP.', $path));
+                }
+
+                $resources['php'][] = $path;
+
+                continue;
+            }
+
+            throw new RuntimeException(\sprintf('Could not open file or directory "%s".', $path));
+        }
 
         foreach ($paths as $path) {
             if (is_dir($path)) {
@@ -446,7 +474,7 @@
 
         $container->setParameter('api_platform.resource_class_directories', $resources['dir']);
 
-        return [$resources['xml'], $resources['yml']];
+        return [$resources['xml'], $resources['yml'], $resources['php']];
     }
 
     private function registerOAuthConfiguration(ContainerBuilder $container, array $config): void

src/Symfony/Bundle/DependencyInjection/Configuration.php

@@ -136,6 +136,9 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->arrayNode('mapping')
                     ->addDefaultsIfNotSet()
                     ->children()
+                        ->arrayNode('imports')
+                            ->prototype('scalar')->end()
+                        ->end()
                         ->arrayNode('paths')
                             ->prototype('scalar')->end()
                         ->end()

src/Symfony/Bundle/Resources/config/metadata/php.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" ?>
+
+<container xmlns="http://symfony.com/schema/dic/services"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+    <services>
+        <service id="api_platform.metadata.resource_extractor.php_file" class="ApiPlatform\Metadata\Extractor\PhpFileResourceExtractor" public="false">
+            <argument type="collection" />
+            <argument type="service" id="service_container" />
+        </service>
+    </services>
+</container>

src/Symfony/Bundle/Resources/config/metadata/resource.xml

@@ -24,6 +24,12 @@
             <argument>%api_platform.graphql.enabled%</argument>
         </service>
 
+        <service id="api_platform.metadata.resource.metadata_collection_factory.php_file" class="ApiPlatform\Metadata\Resource\Factory\PhpFileResourceMetadataCollectionFactory" decorates="api_platform.metadata.resource.metadata_collection_factory" decoration-priority="800" public="false">
+            <argument type="service" id="api_platform.metadata.resource_extractor.php_file" />
+            <argument type="service" id="api_platform.metadata.resource.metadata_collection_factory.php_file.inner" />
+            <argument type="service" id="service_container" on-invalid="null" />
+        </service>
+
         <service id="api_platform.metadata.resource.metadata_collection_factory.concerns" class="ApiPlatform\Metadata\Resource\Factory\ConcernsResourceMetadataCollectionFactory" decorates="api_platform.metadata.resource.metadata_collection_factory" decoration-priority="800" public="false">
             <argument type="service" id="api_platform.metadata.resource.metadata_collection_factory.concerns.inner" />
         </service>

src/Symfony/Bundle/Resources/config/metadata/resource_name.xml

@@ -22,6 +22,11 @@
             <argument type="service" id="api_platform.metadata.resource_extractor.xml" />
         </service>
 
+        <service id="api_platform.metadata.resource.name_collection_factory.php_file" class="ApiPlatform\Metadata\Resource\Factory\PhpFileResourceNameCollectionFactory" decorates="api_platform.metadata.resource.name_collection_factory" decoration-priority="900" public="false">
+            <argument type="service" id="api_platform.metadata.resource_extractor.php_file" />
+            <argument type="service" id="api_platform.metadata.resource.name_collection_factory.php_file.inner" />
+        </service>
+
         <service id="api_platform.metadata.resource.name_collection_factory.concerns" class="ApiPlatform\Metadata\Resource\Factory\ConcernsResourceNameCollectionFactory" decorates="api_platform.metadata.resource.name_collection_factory" decoration-priority="800" public="false">
             <argument>%api_platform.resource_class_directories%</argument>
             <argument type="service" id="api_platform.metadata.resource.name_collection_factory.concerns.inner" />

src/Symfony/Tests/Bundle/DependencyInjection/ApiPlatformExtensionTest.php

@@ -149,6 +149,11 @@
         }
     }
 
+    private function assertContainerHasService(string $service): void
+    {
+        $this->assertTrue($this->container->hasDefinition($service), \sprintf('Service "%s" not found.', $service));
+    }
+
     private function assertNotContainerHasService(string $service): void
     {
         $this->assertFalse($this->container->hasDefinition($service), \sprintf('Service "%s" found.', $service));
@@ -286,4 +291,15 @@
         $this->assertContainerHas($services, $aliases);
         $this->container->hasParameter('api_platform.swagger.http_auth');
     }
+
+    public function testItRegistersMetadataConfiguration(): void
+    {
+        $config = self::DEFAULT_CONFIG;
+        $config['api_platform']['mapping']['imports'] = [__DIR__.'/php'];
+        (new ApiPlatformExtension())->load($config, $this->container);
+
+        $emptyPhpFile = realpath(__DIR__.'/php/empty_file.php');
+        $this->assertContainerHasService('api_platform.metadata.resource_extractor.php_file');
+        $this->assertSame([$emptyPhpFile], $this->container->getDefinition('api_platform.metadata.resource_extractor.php_file')->getArgument(0));
+    }
 }