feat(metadata) customize resource & operations

Author: loic425

src/Metadata/Extractor/AbstractClosureExtractor.php

@@ -0,0 +1,141 @@
+<?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\Extractor;
+
+use Psr\Container\ContainerInterface;
+use Symfony\Component\DependencyInjection\ContainerInterface as SymfonyContainerInterface;
+
+/**
+ * Base file extractor.
+ *
+ * @author Loïc Frémont <[email protected]>
+ */
+abstract class AbstractClosureExtractor implements ClosureExtractorInterface
+{
+    protected ?array $closures = null;
+    private array $collectedParameters = [];
+
+    /**
+     * @param string[] $paths
+     */
+    public function __construct(protected array $paths, private readonly ?ContainerInterface $container = null)
+    {
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getClosures(): array
+    {
+        if (null !== $this->closures) {
+            return $this->closures;
+        }
+
+        $this->closures = [];
+        foreach ($this->paths as $path) {
+            $closure = $this->getPHPFileClosure($path)();
+
+            if (!$closure instanceof \Closure || !$this->isClosureSupported($closure)) {
+                continue;
+            }
+
+            $this->closures[] = $closure;
+        }
+
+        return $this->closures;
+    }
+
+    /**
+     * Check if the closure is supported
+     */
+    abstract protected function isClosureSupported(\Closure $closure): bool;
+
+    /**
+     * Recursively replaces placeholders with the service container parameters.
+     *
+     * @see https://github.com/symfony/symfony/blob/6fec32c/src/Symfony/Bundle/FrameworkBundle/Routing/Router.php
+     *
+     * @copyright (c) Fabien Potencier <[email protected]>
+     *
+     * @param mixed $value The source which might contain "%placeholders%"
+     *
+     * @throws \RuntimeException When a container value is not a string or a numeric value
+     *
+     * @return mixed The source with the placeholders replaced by the container
+     *               parameters. Arrays are resolved recursively.
+     */
+    protected function resolve(mixed $value): mixed
+    {
+        if (null === $this->container) {
+            return $value;
+        }
+
+        if (\is_array($value)) {
+            foreach ($value as $key => $val) {
+                $value[$key] = $this->resolve($val);
+            }
+
+            return $value;
+        }
+
+        if (!\is_string($value)) {
+            return $value;
+        }
+
+        $escapedValue = preg_replace_callback('/%%|%([^%\s]++)%/', function ($match) use ($value) {
+            $parameter = $match[1] ?? null;
+
+            // skip %%
+            if (!isset($parameter)) {
+                return '%%';
+            }
+
+            if (preg_match('/^env\(\w+\)$/', $parameter)) {
+                throw new \RuntimeException(\sprintf('Using "%%%s%%" is not allowed in routing configuration.', $parameter));
+            }
+
+            if (\array_key_exists($parameter, $this->collectedParameters)) {
+                return $this->collectedParameters[$parameter];
+            }
+
+            if ($this->container instanceof SymfonyContainerInterface) {
+                $resolved = $this->container->getParameter($parameter);
+            } else {
+                $resolved = $this->container->get($parameter);
+            }
+
+            if (\is_string($resolved) || is_numeric($resolved)) {
+                $this->collectedParameters[$parameter] = $resolved;
+
+                return (string) $resolved;
+            }
+
+            throw new \RuntimeException(\sprintf('The container parameter "%s", used in the resource configuration value "%s", must be a string or numeric, but it is of type %s.', $parameter, $value, \gettype($resolved)));
+        }, $value);
+
+        return str_replace('%%', '%', $escapedValue);
+    }
+
+    /**
+     * Scope isolated include.
+     *
+     * Prevents access to $this/self from included files.
+     */
+    protected function getPHPFileClosure(string $filePath): \Closure
+    {
+        return \Closure::bind(function () use ($filePath): mixed {
+            return require $filePath;
+        }, null, null);
+    }
+}

src/Metadata/Extractor/ClosureExtractorInterface.php

@@ -0,0 +1,31 @@
+<?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\Extractor;
+
+use ApiPlatform\Metadata\Exception\InvalidArgumentException;
+
+/**
+ * Extracts an array of closure from a file or a list of files.
+ *
+ * @author Loïc Frémont <[email protected]>
+ */
+interface ClosureExtractorInterface
+{
+    /**
+     * Parses all metadata files and convert them in an array.
+     *
+     * @throws InvalidArgumentException
+     */
+    public function getClosures(): array;
+}

src/Metadata/Extractor/PhpFileResourceClosureExtractor.php

@@ -0,0 +1,45 @@
+<?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\Extractor;
+
+use ApiPlatform\Metadata\ApiResource;
+
+/**
+ * Extracts an array of closure from a list of PHP files.
+ *
+ * @author Loïc Frémont <[email protected]>
+ */
+final class PhpFileResourceClosureExtractor extends AbstractClosureExtractor
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function isClosureSupported(\Closure $closure): bool
+    {
+        $resourceReflection = new \ReflectionFunction($closure);
+
+        if (1 !== $resourceReflection->getNumberOfParameters()) {
+            return false;
+        }
+
+        $firstParameterType = ($resourceReflection->getParameters()[0] ?? null)?->getType();
+
+        if (!$firstParameterType instanceof \ReflectionNamedType) {
+            return false;
+        }
+
+        // Check if the closure parameter is an API resource
+        return is_a($firstParameterType->getName(), ApiResource::class, true);
+    }
+}

src/Metadata/Resource/Factory/CustomResourceMetadataCollectionFactory.php

@@ -0,0 +1,57 @@
+<?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\Resource\Factory;
+
+use ApiPlatform\Metadata\Extractor\ClosureExtractorInterface;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+
+final class CustomResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
+{
+    use OperationDefaultsTrait;
+
+    public function __construct(
+        private readonly ClosureExtractorInterface $resourceClosureExtractor,
+        private readonly ?ResourceMetadataCollectionFactoryInterface $decorated = null,
+    ) {
+    }
+
+    public function create(string $resourceClass): ResourceMetadataCollection
+    {
+        $resourceMetadataCollection = new ResourceMetadataCollection($resourceClass);
+        if ($this->decorated) {
+            $resourceMetadataCollection = $this->decorated->create($resourceClass);
+        }
+
+        $newMetadataCollection = new ResourceMetadataCollection($resourceClass);
+
+        foreach  ($resourceMetadataCollection as $resource) {
+            foreach ($this->resourceClosureExtractor->getClosures() as  $closure) {
+                $resource = $closure($resource);
+
+                $operations = [];
+                foreach ($resource->getOperations() as $operation) {
+                    [$key, $operation] = $this->getOperationWithDefaults($resource, $operation);
+                    $operations[$key] = $operation;
+                }
+
+                $resource = $resource->withOperations(new Operations($operations));
+            }
+
+            $newMetadataCollection[] = $resource;
+        }
+
+        return $newMetadataCollection;
+    }
+}

src/Metadata/Tests/Extractor/PhpFileResourceClosureExtractorTest.php

@@ -0,0 +1,39 @@
+<?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\Tests\Extractor;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Extractor\PhpFileResourceClosureExtractor;
+use PHPUnit\Framework\TestCase;
+
+final class PhpFileResourceClosureExtractorTest extends TestCase
+{
+    public function testItGetsClosuresFromPhpFileThatReturnsAnApiResource(): void
+    {
+        $extractor = new PhpFileResourceClosureExtractor([__DIR__.'/php/valid_custom_resource_php_file.php']);
+
+        $expectedClosures = [static function (ApiResource $resource): ApiResource {
+            return $resource->withShortName('dummy');
+        }];
+
+        $this->assertEquals($expectedClosures, $extractor->getClosures());
+    }
+
+    public function testItExcludesClosuresFromPhpFileThatDoesNotReturnAnApiResource(): void
+    {
+        $extractor = new PhpFileResourceClosureExtractor([__DIR__.'/php/invalid_custom_php_file.php']);
+
+        $this->assertEquals([], $extractor->getClosures());
+    }
+}

src/Metadata/Tests/Extractor/php/invalid_custom_php_file.php

@@ -0,0 +1,14 @@
+<?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);
+
+return static function (): void {};

src/Metadata/Tests/Extractor/php/valid_custom_resource_php_file.php

@@ -0,0 +1,18 @@
+<?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);
+
+use ApiPlatform\Metadata\ApiResource;
+
+return static function (ApiResource $resource): ApiResource {
+    return $resource->withShortName('dummy');
+};