External routing files (#1035)

| Q               | A
| --------------- | -----
| Bug fix?        | no
| New feature?    | yes
| BC breaks?      | no
| Deprecations?   | no
| Related tickets | fixes #1029
| License         | MIT

Very similar to api-platform/core#7017
but in Sylius resource context (for HTML routing)

```php
<?php
// config/sylius/resources/speaker.php
declare(strict_types=1);

use Sylius\Resource\Metadata\Create;
use Sylius\Resource\Metadata\ResourceMetadata;
use Sylius\Resource\Metadata\Update;
use Sylius\Resource\Metadata\Operations;
use App\Entity\Speaker;

return new ResourceMetadata()
    ->withClass(Speaker::class)
    ->withOperations(new Operations([
        new Create(),
        new Update(),
    ]))
;
```

Author: NoResponseMate

.github/workflows/build.yml

@@ -183,6 +183,7 @@ jobs:
             -
                 name: Create-project with skeleton
                 run: |
+                    set -x
                     composer create-project --ansi "symfony/skeleton:${{ matrix.skeleton }}" skeleton_app
                     cd skeleton_app
                     composer config extra.symfony.allow-contrib true

phpstan.neon

@@ -62,6 +62,7 @@ parameters:
         - '/Method Sylius\\Bundle\\ResourceBundle\\Event\\ResourceControllerEvent::stop\(\) has no return typehint specified./'
         - '/Method Sylius\\Bundle\\ResourceBundle\\Form\\Extension\\HttpFoundation\\HttpFoundationRequestHandler::handleRequest\(\) has no return typehint specified./'
         - '/Method Sylius\\Bundle\\ResourceBundle\\Grid\\Controller\\ResourcesResolver::getResources\(\) has no return typehint specified./'
+        - '/Method Sylius\\Resource\\Metadata\\Extractor\\AbstractResourceExtractor::getResources\(\) should return array<Sylius\\Resource\\Metadata\\ResourceMetadata> but returns array<Sylius\\Resource\\Metadata\\ResourceMetadata>\|null./'
         - '/Method Sylius\\Resource\\Model\\ResourceInterface::getId\(\) has no return typehint specified./'
         - '/Method Sylius\\Resource\\Model\\TimestampableInterface::setCreatedAt\(\) has no return typehint specified./'
         - '/Method Sylius\\Resource\\Model\\TimestampableInterface::setUpdatedAt\(\) has no return typehint specified./'

psalm.xml

@@ -120,6 +120,7 @@
         <InvalidReturnType>
             <errorLevel type="suppress">
                 <file name="src/Component/src/Doctrine/Persistence/InMemoryRepository.php" />
+                <file name="src/Component/src/Metadata/Extractor/PhpFileResourceExtractor.php" />
             </errorLevel>
         </InvalidReturnType>
 
@@ -173,6 +174,12 @@
             </errorLevel>
         </MoreSpecificImplementedParamType>
 
+        <NullableReturnStatement>
+            <errorLevel type="suppress">
+                <file name="src/Component/src/Metadata/Extractor/PhpFileResourceExtractor.php" />
+            </errorLevel>
+        </NullableReturnStatement>
+
         <NullArgument>
             <errorLevel type="suppress">
                 <directory name="src" />
@@ -321,6 +328,12 @@
             </errorLevel>
         </UnrecognizedStatement>
 
+        <UnresolvableInclude>
+            <errorLevel type="suppress">
+                <file name="src/Component/src/Metadata/Extractor/PhpFileResourceExtractor.php" />
+            </errorLevel>
+        </UnresolvableInclude>
+
         <UnsupportedReferenceUsage>
             <errorLevel type="suppress">
                 <file name="src/Component/src/Doctrine/Persistence/InMemoryRepository.php" />

src/Bundle/DependencyInjection/Configuration.php

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

src/Bundle/DependencyInjection/SyliusResourceExtension.php

@@ -33,11 +33,14 @@
 use Sylius\Resource\Twig\Context\Factory\ContextFactoryInterface;
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\Config\Loader\LoaderInterface;
+use Symfony\Component\Config\Resource\DirectoryResource;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
+use Symfony\Component\DependencyInjection\Exception\RuntimeException;
 use Symfony\Component\DependencyInjection\Extension\Extension;
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
+use Symfony\Component\Finder\Finder;
 use function Symfony\Component\String\u;
 
 final class SyliusResourceExtension extends Extension implements PrependExtensionInterface
@@ -66,6 +69,7 @@ public function load(array $configs, ContainerBuilder $container): void
         $container->setParameter('sylius.resource.settings', $config['settings']);
         $container->setAlias('sylius.resource_controller.authorization_checker', $config['authorization_checker']);
 
+        $this->registerMetadataConfiguration($container, $config);
         $this->autoRegisterResources($config, $container);
 
         $this->loadPersistence($config['drivers'], $config['resources'], $loader, $container);
@@ -320,4 +324,43 @@ private function loadResources(array $loadedResources, ContainerBuilder $contain
             }
         }
     }
+
+    private function registerMetadataConfiguration(ContainerBuilder $container, array $config): void
+    {
+        $resources = $this->getResourceFilesToWatch($container, $config);
+
+        $container->getDefinition('sylius.metadata.resource_extractor.php_file')->replaceArgument(0, $resources);
+    }
+
+    private function getResourceFilesToWatch(ContainerBuilder $container, array $config): array
+    {
+        $files = [];
+
+        /** @var string $path */
+        foreach ($config['mapping']['imports'] ?? [] as $path) {
+            if (is_dir($path)) {
+                foreach (Finder::create()->followLinks()->files()->in($path)->name('/\.php$/')->sortByName() as $file) {
+                    $files[] = $file->getRealPath();
+                }
+
+                $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));
+                }
+
+                $files[] = $path;
+
+                continue;
+            }
+
+            throw new RuntimeException(\sprintf('Could not open file or directory "%s".', $path));
+        }
+
+        return $files;
+    }
 }

src/Bundle/Resources/config/services/metadata/extractor.xml

@@ -0,0 +1,8 @@
+<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="sylius.metadata.resource_extractor.php_file" class="Sylius\Resource\Metadata\Extractor\PhpFileResourceExtractor" public="false">
+            <argument type="collection" />
+            <argument type="service" id="service_container" />
+        </service>
+    </services>
+</container>

src/Bundle/Resources/config/services/metadata/resource_class_list.xml

@@ -22,5 +22,15 @@
             <argument>%sylius.resource.mapping%</argument>
         </service>
         <service id="Sylius\Resource\Metadata\Resource\Factory\AttributesResourceClassListFactory" alias="sylius.metadata.resource_class_list.factory.attributes" />
+
+        <service id="sylius.metadata.resource_class_list.factory.php_file"
+                 class="Sylius\Resource\Metadata\Resource\Factory\PhpFileResourceClassListFactory"
+                 decorates="sylius.metadata.resource_class_list.factory"
+                 decoration-priority="100"
+        >
+            <argument type="service" id="sylius.metadata.resource_extractor.php_file" />
+            <argument type="service" id=".inner" />
+        </service>
+        <service id="Sylius\Resource\Metadata\Resource\Factory\PhpFileResourceClassListFactory" alias="sylius.metadata.resource_class_list.factory.php_file" />
     </services>
 </container>

src/Bundle/Resources/config/services/metadata/resource_metadata_collection.xml

@@ -17,16 +17,28 @@
             <tag name="cache.pool" />
         </service>
 
+        <service id="sylius.resource_metadata_collection.factory" alias="sylius.resource_metadata_collection.factory.attributes" />
+        <service id="Sylius\Resource\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface" alias="sylius.resource_metadata_collection.factory.attributes" />
+
         <service id="sylius.resource_metadata_collection.factory.attributes" class="Sylius\Resource\Metadata\Resource\Factory\AttributesResourceMetadataCollectionFactory">
             <argument type="service" id="sylius.resource_registry" />
             <argument type="service" id="sylius.routing.factory.operation_route_name_factory" />
         </service>
-        <service id="Sylius\Resource\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface" alias="sylius.resource_metadata_collection.factory.attributes" />
-        <service id="sylius.resource_metadata_collection.factory" alias="sylius.resource_metadata_collection.factory.attributes" />
+
+        <service id="sylius.resource_metadata_collection.factory.php_file"
+                 class="Sylius\Resource\Metadata\Resource\Factory\PhpFileResourceMetadataCollectionFactory"
+                 decorates="sylius.resource_metadata_collection.factory"
+                 decoration-priority="400"
+        >
+            <argument type="service" id="sylius.resource_registry" />
+            <argument type="service" id="sylius.routing.factory.operation_route_name_factory" />
+            <argument type="service" id="sylius.metadata.resource_extractor.php_file" />
+            <argument type="service" id=".inner" />
+        </service>
 
         <service id="sylius.resource_metadata_collection.factory.state_machine"
                  class="Sylius\Resource\Metadata\Resource\Factory\StateMachineResourceMetadataCollectionFactory"
-                 decorates="sylius.resource_metadata_collection.factory.attributes"
+                 decorates="sylius.resource_metadata_collection.factory"
                  decoration-priority="300"
         >
             <argument type="service" id="sylius.resource_registry" />
@@ -83,15 +95,15 @@
 
         <service id="sylius.resource_metadata_collection.factory.templates_dir"
                  class="Sylius\Resource\Metadata\Resource\Factory\TemplatesDirResourceMetadataCollectionFactory"
-                 decorates="sylius.resource_metadata_collection.factory.attributes"
+                 decorates="sylius.resource_metadata_collection.factory"
         >
             <argument type="service" id=".inner" />
             <argument>%sylius.resource.settings%</argument>
         </service>
 
         <service id="sylius.resource_metadata_collection.factory.cached"
                  class="Sylius\Resource\Metadata\Resource\Factory\CachedResourceMetadataCollectionFactory"
-                 decorates="sylius.resource_metadata_collection.factory.attributes"
+                 decorates="sylius.resource_metadata_collection.factory"
                  decoration-priority="-10"
         >
             <argument type="service" id="sylius.cache.metadata.resource_collection" />

src/Component/src/Metadata/Extractor/AbstractResourceExtractor.php

@@ -0,0 +1,125 @@
+<?php
+
+/*
+ * This file is part of the Sylius package.
+ *
+ * (c) Sylius Sp. z o.o.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Sylius\Resource\Metadata\Extractor;
+
+use Psr\Container\ContainerInterface;
+use Sylius\Resource\Exception\RuntimeException;
+use Sylius\Resource\Metadata\ResourceMetadata;
+use Symfony\Component\DependencyInjection\ContainerInterface as SymfonyContainerInterface;
+
+/**
+ * Base file extractor.
+ *
+ * @experimental
+ */
+abstract class AbstractResourceExtractor implements ResourceExtractorInterface
+{
+    /** @var ResourceMetadata[]|null */
+    protected ?array $resources = null;
+
+    private array $collectedParameters = [];
+
+    /** @param string[] $paths */
+    public function __construct(
+        protected array $paths,
+        private readonly ?ContainerInterface $container = null,
+    ) {
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getResources(): array
+    {
+        if (null !== $this->resources) {
+            return $this->resources;
+        }
+
+        $this->resources = [];
+        foreach ($this->paths as $path) {
+            $this->extractFromPath($path);
+        }
+
+        return $this->resources;
+    }
+
+    /**
+     * Extracts metadata from a given path.
+     */
+    abstract protected function extractFromPath(string $path): void;
+
+    /**
+     * Recursively replaces placeholders with the service container parameters.
+     *
+     * @see https://github.com/symfony/symfony/blob/6fec32c/src/Symfony/Bundle/FrameworkBundle/Routing/Router.php
+     *
+     * @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 ?? '');
+    }
+}

src/Component/src/Metadata/Extractor/PhpFileResourceExtractor.php

@@ -0,0 +1,53 @@
+<?php
+
+/*
+ * This file is part of the Sylius package.
+ *
+ * (c) Sylius Sp. z o.o.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Sylius\Resource\Metadata\Extractor;
+
+use Sylius\Resource\Metadata\ResourceMetadata;
+
+/**
+ * @experimental
+ */
+final class PhpFileResourceExtractor extends AbstractResourceExtractor
+{
+    protected function extractFromPath(string $path): void
+    {
+        $resource = $this->getPHPFileClosure($path)();
+
+        if (!$resource instanceof ResourceMetadata) {
+            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);
+    }
+}