feat(metadata) Customize Resource & operations (#1055)

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

It's the same feature as [this APIP
one](api-platform/core#7213).
We need this feature for [this
issue](Sylius/Sylius#18212).

Author: NoResponseMate

phpstan.neon

@@ -44,6 +44,9 @@ parameters:
         # return type mixed of method ParameterBag::get()"
         - 'src/Bundle/Controller/Parameters.php'
 
+        # ResourceMetadata will need to use the generic T
+        - 'src/Component/src/Metadata/ResourceMetadata.php'
+
     ignoreErrors:
         # Optional MongoDB ODM support - requires doctrine/mongodb-odm-bundle package
         # These classes are only loaded when MongoDB driver is configured and the bundle is installed
@@ -94,6 +97,9 @@ parameters:
         # See: src/Bundle/DependencyInjection/Configuration.php:30-37
         - '/Call to an undefined method Symfony\\Component\\Config\\Definition\\Builder\\NodeParentInterface::(end|variableNode|scalarNode)\(\)/'
 
+        # Symfony Dependency Injection Component can use ReflectionClass type as second argument instead of Reflector one.
+        -  '/Parameter #2 \$configurator of method Symfony\\Component\\DependencyInjection\\ContainerBuilder::registerAttributeForAutoconfiguration\(\)/'
+
         # Backward compatibility for Symfony DependencyInjection Alias::setDeprecated()
         # Method signature changed between Symfony versions:
         # - Symfony < 5.1: setDeprecated($status, $message)

psalm.xml

@@ -39,6 +39,7 @@
                 <referencedFunction name="Doctrine\Persistence\ObjectManager::getClassMetadata" />
                 <referencedFunction name="ReflectionClass::getAttributes" />
                 <file name="src/Bundle/Form/DataTransformer/CollectionToStringTransformer.php" />
+                <file name="src/Bundle/DependencyInjection/SyliusResourceExtension.php" />
                 <file name="src/Component/src/Doctrine/Persistence/InMemoryRepository.php" />
                 <file name="src/Component/src/Symfony/Request/State/Provider.php" />
             </errorLevel>
@@ -153,6 +154,12 @@
             </errorLevel>
         </MissingClassConstType>
 
+        <MissingConstructor>
+            <errorLevel type="suppress">
+                <file name="src/Component/src/Metadata/Mutator/ResourceMutatorCollection.php" />
+            </errorLevel>
+        </MissingConstructor>
+
         <MissingParamType>
             <errorLevel type="suppress">
                 <file name="src/Bundle/Routing/ResourceLoader.php" />

src/Bundle/DependencyInjection/SyliusResourceExtension.php

@@ -23,9 +23,13 @@
 use Sylius\Component\Resource\Factory\FactoryInterface as LegacyFactoryInterface;
 use Sylius\Resource\Factory\Factory;
 use Sylius\Resource\Factory\FactoryInterface;
+use Sylius\Resource\Metadata\AsOperationMutator;
 use Sylius\Resource\Metadata\AsResource;
+use Sylius\Resource\Metadata\AsResourceMutator;
 use Sylius\Resource\Metadata\Metadata;
+use Sylius\Resource\Metadata\OperationMutatorInterface;
 use Sylius\Resource\Metadata\ResourceMetadata;
+use Sylius\Resource\Metadata\ResourceMutatorInterface;
 use Sylius\Resource\Reflection\ClassReflection;
 use Sylius\Resource\State\ProcessorInterface;
 use Sylius\Resource\State\ProviderInterface;
@@ -34,6 +38,7 @@
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\Config\Loader\LoaderInterface;
 use Symfony\Component\Config\Resource\DirectoryResource;
+use Symfony\Component\DependencyInjection\ChildDefinition;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
 use Symfony\Component\DependencyInjection\Exception\RuntimeException;
@@ -76,6 +81,32 @@ public function load(array $configs, ContainerBuilder $container): void
         $this->loadPersistence($config['drivers'], $config['resources'], $loader, $container);
         $this->loadResources($config['resources'], $container);
 
+        $container->registerAttributeForAutoconfiguration(
+            AsResourceMutator::class,
+            static function (ChildDefinition $definition, AsResourceMutator $attribute, \ReflectionClass $reflector): void {
+                if (!is_a($reflector->name, ResourceMutatorInterface::class, true)) {
+                    throw new RuntimeException(\sprintf('Resource mutator "%s" should implement %s', $reflector->name, ResourceMutatorInterface::class));
+                }
+
+                $definition->addTag('sylius.resource_mutator', [
+                    'resourceClass' => $attribute->resourceClass,
+                ]);
+            },
+        );
+
+        $container->registerAttributeForAutoconfiguration(
+            AsOperationMutator::class,
+            static function (ChildDefinition $definition, AsOperationMutator $attribute, \ReflectionClass $reflector): void {
+                if (!is_a($reflector->name, OperationMutatorInterface::class, true)) {
+                    throw new RuntimeException(\sprintf('Operation mutator "%s" should implement %s', $reflector->name, OperationMutatorInterface::class));
+                }
+
+                $definition->addTag('sylius.operation_mutator', [
+                    'operationName' => $attribute->operationName,
+                ]);
+            },
+        );
+
         $container->registerForAutoconfiguration(ProviderInterface::class)
             ->addTag('sylius.state_provider')
         ;

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

@@ -1,3 +1,16 @@
+<?xml version="1.0" ?>
+
+<!--
+
+ 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.
+
+-->
+
 <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">

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

@@ -0,0 +1,23 @@
+<?xml version="1.0" ?>
+
+<!--
+
+ 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.
+
+-->
+
+<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.mutator_collection.resource" class="Sylius\Resource\Metadata\Mutator\ResourceMutatorCollection" public="false" />
+
+        <service id="sylius.metadata.mutator_collection.operation" class="Sylius\Resource\Metadata\Mutator\OperationMutatorCollection" public="false" />
+    </services>
+</container>

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

@@ -36,6 +36,15 @@
             <argument type="service" id=".inner" />
         </service>
 
+        <service id="sylius.metadata.resource.metadata_collection_factory.mutator"
+                 class="Sylius\Resource\Metadata\Resource\Factory\MutatorResourceMetadataCollectionFactory"
+                 decorates="sylius.resource_metadata_collection.factory"
+                 decoration-priority="400">
+            <argument type="service" id="sylius.metadata.mutator_collection.resource" />
+            <argument type="service" id="sylius.metadata.mutator_collection.operation" />
+            <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"

src/Bundle/SyliusResourceBundle.php

@@ -31,6 +31,7 @@
 use Sylius\Bundle\ResourceBundle\DependencyInjection\PagerfantaExtension;
 use Sylius\Resource\Symfony\DependencyInjection\Compiler\DisableMetadataCachePass;
 use Sylius\Resource\Symfony\DependencyInjection\Compiler\FallbackToKernelDefaultLocalePass;
+use Sylius\Resource\Symfony\DependencyInjection\Compiler\MetadataMutatorPass;
 use Symfony\Component\DependencyInjection\Compiler\PassConfig;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\HttpKernel\Bundle\Bundle;
@@ -54,6 +55,7 @@ public function build(ContainerBuilder $container): void
         $container->addCompilerPass(new FallbackToKernelDefaultLocalePass());
         $container->addCompilerPass(new DoctrineContainerRepositoryFactoryPass());
         $container->addCompilerPass(new DoctrineTargetEntitiesResolverPass(new TargetEntitiesResolver()), PassConfig::TYPE_BEFORE_OPTIMIZATION, 1);
+        $container->addCompilerPass(new MetadataMutatorPass());
         $container->addCompilerPass(new RegisterFormBuilderPass());
         $container->addCompilerPass(new RegisterFqcnControllersPass());
         $container->addCompilerPass(new RegisterResourceRepositoryPass());

src/Component/src/Metadata/AsOperationMutator.php

@@ -0,0 +1,23 @@
+<?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;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class AsOperationMutator
+{
+    public function __construct(
+        public readonly string $operationName,
+    ) {
+    }
+}

src/Component/src/Metadata/AsResourceMutator.php

@@ -0,0 +1,26 @@
+<?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;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class AsResourceMutator
+{
+    /**
+     * @param class-string $resourceClass
+     */
+    public function __construct(
+        public readonly string $resourceClass,
+    ) {
+    }
+}

src/Component/src/Metadata/Mutator/OperationMutatorCollection.php

@@ -0,0 +1,43 @@
+<?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\Mutator;
+
+use Sylius\Resource\Metadata\OperationMutatorInterface;
+
+/**
+ * @internal
+ */
+final class OperationMutatorCollection implements OperationMutatorCollectionInterface
+{
+    /** @var array<string, list<OperationMutatorInterface>> */
+    private array $mutators = [];
+
+    /**
+     * Adds a mutator to the container for a given operation name.
+     */
+    public function add(string $operationName, OperationMutatorInterface $mutator): void
+    {
+        $this->mutators[$operationName][] = $mutator;
+    }
+
+    public function get(string $id): array
+    {
+        return $this->mutators[$id] ?? [];
+    }
+
+    public function has(string $id): bool
+    {
+        return isset($this->mutators[$id]);
+    }
+}