feat(symfony): Autoconfigure classes using `#[ApiResource]` attribute #6943

GromNaN · 2025-02-05T10:31:30Z

Q	A
Branch?	main
Tickets	-
License	MIT
Doc PR	todo

Using the Symfony bundle, classes with the #[ApiResource] attribute must be in src/ApiResource, src/Entity (for Doctrine ORM) or src/Document (for MongoDB ODM). It's possible to add custom paths in the configuration, but that's one more little thing to take care of.

By using the Symfony autoconfiguration feature, we can detect classes with the #[ApiResource] attribute during the build of the container instead of scanning directories at runtime.

The same feature was implemented in Symfony for the #[JsonEncodable] attribute: symfony/symfony#59401

src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

src/Symfony/Bundle/DependencyInjection/Compiler/AttributeResourcePass.php

dunglas

Very smart! I like this.

soyuka · 2025-02-06T07:43:36Z

Nice! It reminds me a discussion we had with @nicolas-grekas ^^.
I'm wondering a few things, do we still need:

core/src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

Lines 342 to 348 in 7b3bf83

    
           private function getClassNameResources(): array 
        
           { 
        
               return [ 
        
                   Error::class, 
        
                   ValidationException::class, 
        
               ]; 
        
           }

The way api_platform.class_name_resources works right now it's called by api_platform.metadata.resource.name_collection_factory.class_name, until this patch classes were discovered using api_platform.resource_class_directories inside api_platform.metadata.resource.name_collection_factory.attributes. Shouldn't we clean that part of the code to remove php files?

core/src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

Lines 385 to 433 in 7b3bf83

    
           $paths = array_unique(array_merge($this->getBundlesResourcesPaths($container, $config), $config['mapping']['paths'])); 
        
           if (!$config['mapping']['paths']) { 
        
               $projectDir = $container->getParameter('kernel.project_dir'); 
        
               foreach (["$projectDir/config/api_platform", "$projectDir/src/ApiResource"] as $dir) { 
        
                   if (is_dir($dir)) { 
        
                       $paths[] = $dir; 
        
                   } 
        
               } 
        
               if ($this->isConfigEnabled($container, $config['doctrine']) && is_dir($doctrinePath = "$projectDir/src/Entity")) { 
        
                   $paths[] = $doctrinePath; 
        
               } 
        
               if ($this->isConfigEnabled($container, $config['doctrine_mongodb_odm']) && is_dir($documentPath = "$projectDir/src/Document")) { 
        
                   $paths[] = $documentPath; 
        
               } 
        
           } 
        
           $resources = ['yml' => [], 'xml' => [], 'dir' => []]; 
        
           foreach ($paths as $path) { 
        
               if (is_dir($path)) { 
        
                   foreach (Finder::create()->followLinks()->files()->in($path)->name('/\.(xml|ya?ml)$/')->sortByName() as $file) { 
        
                       $resources['yaml' === ($extension = $file->getExtension()) ? 'yml' : $extension][] = $file->getRealPath(); 
        
                   } 
        
                   $resources['dir'][] = $path; 
        
                   $container->addResource(new DirectoryResource($path, '/\.(xml|ya?ml|php)$/')); 
        
                   continue; 
        
               } 
        
               if ($container->fileExists($path, false)) { 
        
                   if (!preg_match('/\.(xml|ya?ml)$/', (string) $path, $matches)) { 
        
                       throw new RuntimeException(\sprintf('Unsupported mapping type in "%s", supported types are XML & YAML.', $path)); 
        
                   } 
        
                   $resources['yaml' === $matches[1] ? 'yml' : $matches[1]][] = $path; 
        
                   continue; 
        
               } 
        
               throw new RuntimeException(\sprintf('Could not open file or directory "%s".', $path)); 
        
           } 
        
           $container->setParameter('api_platform.resource_class_directories', $resources['dir']); 
        
           return [$resources['xml'], $resources['yml']];

This is quite heavy work for no real gain, especially that the resources discovered with this patch will already be discovered there right?

Last thing, inside the route loader we declare directory resources (so that the container is rebuilt when these file changes) at:

core/src/Symfony/Routing/ApiLoader.php

Lines 52 to 54 in 7b3bf83

    
           foreach ($this->resourceClassDirectories as $directory) { 
        
               $routeCollection->addResource(new DirectoryResource($directory, '/\.php$/')); 
        
           }

If we remove that api_platform.resource_class_directories for php files, we can also remove these lines but we may need to add something to handle these no?

GromNaN · 2025-02-06T09:45:18Z

Removing the directory scanning would be a breaking change as the Entity directory is excluded by default from the services config (see FrameworkBundle recipe).

Of-course, this is the target.

soyuka · 2025-02-06T13:42:51Z

Mhh okay but this means that we only need this for the Entity directory, we can remove all the code handling our paths (for example ApiResource). What about the DirectoryResource to rebuild the container on file change? Are services tagged as container.excluded watched by Symfony?

dunglas · 2025-02-06T19:50:38Z

If this doesn’t work for the Entity directory (that we won’t deprecate IMHO), then is this patch really useful?
We’ll have 2 systems to maintain basically forever instead of one 😅

GromNaN · 2025-02-06T22:41:30Z

Let's reintroduce the src/Entity dir in the DI config: doctrine/DoctrineBundle#1868

I'll try to move the directory scan to the compiler pass.

…source_class_directories

GromNaN · 2025-02-10T13:33:08Z

Well, I haven't found a solution yet to avoid scanning the configured folders twice (all the Entity, Document and ApiResource folders of the project and bundles).

If this doesn’t work for the Entity directory (that we won’t deprecate IMHO), then is this patch really useful?
This PR doesn't bring any performance gain, but at least it enables a feature: the ability to put ApiResource classes in any directory or the project without additional configuration.

…)` and `ContainerBuilder::findExcludedServiceIds()` for auto-discovering value-objects (GromNaN) This PR was squashed before being merged into the 7.3 branch. Discussion ---------- [DependencyInjection] Add `Definition::addExcludedTag()` and `ContainerBuilder::findExcludedServiceIds()` for auto-discovering value-objects | Q | A | ------------- | --- | Branch? | 7.3 | Bug fix? | no | New feature? | yes | Deprecations? | no | Issues | - | License | MIT We could **not** use the method `findTaggedServiceIds` in #59401 (comment), same for api-platform/core#6943. As "using the container loading tools to do resource discovery quite seamlessly" [seems to be a good idea](#59401 (review)), this changes make it easier. I'm not closed to alternative ideas if we want to go further with this use-case. ### Usage Let's create a `AppModel` attribute class and use it on any class of the project. In the extension class: ```php $this->registerAttributeForAutoconfiguration(AppModel::class, static function (ChildDefinition $definition) { $definition->addExcludedTag('app.model'); }); ``` In a compiler pass: ```php $classes = []; foreach($containerBuilder->findExcludedServiceIds('app.model') as $id => $tags) { $classes[] = $containerBuilder->getDefinition($id)->getClass(); } $containerBuilder->setParameter('.app.model_classes', $classes); ``` And this parameter can be injected into a service, or directly update a service definition to inject this list of classes. The attribute parameters can be injected into the tag, and retrieved in the compiler pass, for more advanced configuration. Commits ------- 7a0443b [DependencyInjection] Add `Definition::addExcludedTag()` and `ContainerBuilder::findExcludedServiceIds()` for auto-discovering value-objects

GromNaN · 2025-02-11T14:03:49Z

So I think we need to move the extraction of the classes names into the compiler pass and inject them into a ClassNameResourceNameCollectionFactory. The CachedResourceNameCollectionFactory can then be removed.

GromNaN · 2025-03-13T11:07:26Z

Here's how it should be designed to take full advantage of the container builder.

Goals

Enable auto-discovery of #[ApiResource] classes anywhere
Build the list of "resource" classes during container compilation

Advantage: no need for additional cache unless explicitly required by a custom implementation CachedResourceNameCollectionFactory.

Backward-compatibility constraints:

src/ApiResource, src/Entity, src/Document directories must be scanned even if they are not in the DIC autoconfigure paths. This can be deprecated.
Keep support for custom ResourceNameCollectionFactoryInterface services
Keep support for XML/Yaml files: Detection should be similar to any other config files (doctrine.yaml, validation.yaml with registerMappingFilesFromConfig

Attributes

Detection: Use Symfony ContainerBuilder::registerAttributeForAutoconfiguration() to list all the classes that use the #[ApiResource] attribute and inject them into a ClassNameResourceNameCollectionFactory.

Cache invalidation: The Symfony cache is automatically invalidated and regenerated when one of this classes is modified, removed or added in the autoconfigured directories.

XML/Yaml files

Detection:: List files during container compilation.

Cache invalidation: Adding this files and directories as "resources"; even if they doesn't exist, the container cache is automatically invalidated and regenerated when on of the files is modified, removed or added in the configured directories.

Nayte91 · 2025-04-09T12:28:18Z

Hello, I may miss a link in this discussion, but I didn't see here anything related to symfony/symfony#59987 as for SF7.3 #[Entity] tagged classes will be automatically excluded from services, and therefore default config.yaml services definition folders will be cleaned.

Sorry if already mentionned.

soyuka · 2025-04-29T07:47:10Z

For now we can merge this as-is, we'll deprecate the resource_class_directories, mapping.paths and add a flag to skip resource class directories.

soyuka · 2025-04-29T07:47:27Z

thanks @GromNaN!

…api-platform#6943)

michaljusiega · 2025-07-02T20:35:15Z

src/Symfony/Bundle/DependencyInjection/Configuration.php

@@ -141,6 +141,7 @@ public function getConfigTreeBuilder(): TreeBuilder
                ->end()
                ->arrayNode('resource_class_directories')
                    ->prototype('scalar')->end()
+                    ->setDeprecated('api-platform/symfony', '4.1', 'The "resource_class_directories" configuration is deprecated, classes using #[ApiResource] attribute are autoconfigured by the dependency injection container.')


@soyuka @GromNaN

I think, this feature break some functionality.

If this option was deprecated, and planned to be removed in future, this will break any additional features like filters (sorting/filtering) on the same level as #[ApiResource] in resource - this means they are not loaded with all the operations they are should be.

Simple reproducer:
api-platform/core:4.2.x-dev

<?php use ApiPlatform\Doctrine\Common\Filter\SearchFilterInterface; use ApiPlatform\Doctrine\Orm\Filter\SearchFilter; use ApiPlatform\Metadata\ApiFilter; use ApiPlatform\Metadata\ApiResource; use ApiPlatform\Metadata\GetCollection; use ApiPlatform\OpenApi\Model\Operation; use App\Expense\Application\Controller\GetCollectionCostController; use App\Shared\Domain\Entity\AbstractEntity; #[ApiResource( operations: [ new GetCollection( uriTemplate: 'expense/cost', inputFormats: ['jsonld' => ['application/ld+json']], outputFormats: ['jsonld' => ['application/ld+json']], controller: GetCollectionCostController::class, openapi: new Operation(tags: ['Expense'], summary: 'Returns the collection of Cost resources.', description: 'Returns the collection of Cost resources.'), normalizationContext: ['groups' => ['api:read']], denormalizationContext: ['groups' => ['api:write']], output: Cost::class, priority: 2, ), ], )] #[ApiFilter(filterClass: SearchFilter::class, properties: ['comment' => SearchFilterInterface::STRATEGY_IPARTIAL])] class Cost extends AbstractEntity { }

With setting resource_class_directories:

and deprecated message:
Since api-platform/symfony 4.1: The "resource_class_directories" configuration is deprecated, classes using #[ApiResource] attribute are autoconfigured by the dependency injection container.

Without setting resource_class_directories:

I don't know how to fix it. Unless there is some other way to fix it?

Settings the #[ApiFilter] attribute directly on property (like in https://api-platform.com/docs/core/filters/#apifilter-attribute) also not works.

Interesting thanks I'll investigate

Do you have any information about that @soyuka ?

Should other attributes such as #[ApiFilter] be added to the AutoConfiguration?

I tried to achive the same result as is in https://api-platform.com/docs/core/filters/#filtering-multiple-properties-with-property and I failed...

Cannot instance new SearchFilter like wrote in docs (because of required arguments like ManagerRegistry)...

So for me +1 to keep ApiFilter class to be not deprecated.

Additionally, ApiFilter scans all fields and adds all possible combinations.

We will not achieve this in the way described in the documentation (you have to write each field separately) :(

Please, let's make ApiFilter to be automatically autoconfigured ;)

We're working on filter compatibility, searching is at #7121.

Additionally, ApiFilter scans all fields and adds all possible combinations.

And its really bad at doing this, for example it'll use a search filter on everything though it should only for strings. There are lots of wrong usage of filters because of this (people trying to use SearchFilter on dates for example).

Don't worry I'm not deprecating ApiFilter right now, and yes there will be a script to transform your filters to parameters automatically.

This is a journey that started almost 5 years ago for me and I'll go through and I don't want to break existing code ovbiously, but ApiFilter is poor engineering and needs to be changed for a better developer experience.

TLDR: ignore the deprecation for now.

Thank you very much for response. I already know what way further development goes.

GromNaN commented Feb 5, 2025

View reviewed changes

src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php Outdated Show resolved Hide resolved

GromNaN force-pushed the autoconfigure branch 2 times, most recently from 24c6b04 to 939fe53 Compare February 5, 2025 10:36

GromNaN commented Feb 5, 2025

View reviewed changes

src/Symfony/Bundle/DependencyInjection/Compiler/AttributeResourcePass.php Outdated Show resolved Hide resolved

GromNaN marked this pull request as ready for review February 5, 2025 12:33

GromNaN changed the title ~~feat(symfony): Autoconfigure resource dirs using #[ApiResource] attribute~~ feat(symfony): Autoconfigure resource classes using #[ApiResource] attribute Feb 5, 2025

GromNaN changed the title ~~feat(symfony): Autoconfigure resource classes using #[ApiResource] attribute~~ feat(symfony): Autoconfigure classes using #[ApiResource] attribute Feb 5, 2025

GromNaN mentioned this pull request Feb 5, 2025

[DependencyInjection] Add Definition::addExcludedTag() and ContainerBuilder::findExcludedServiceIds() for auto-discovering value-objects symfony/symfony#59704

Merged

dunglas approved these changes Feb 5, 2025

View reviewed changes

GromNaN mentioned this pull request Feb 6, 2025

Ensure classes using the #[Entity] attribute are not declared as service doctrine/DoctrineBundle#1868

Merged

soyuka mentioned this pull request Feb 7, 2025

perf: various optimizations for Laravel/Symfony #6954

Merged

GromNaN added 3 commits February 10, 2025 14:14

feat(symfony): Autoconfigure resource dirs using ApiResource attribute

b15ee77

Override api_platform.class_name_resources instead of api_platform.re…

2f49ba9

…source_class_directories

feat(symfony): Deprecate resource_class_directories config

d2a7a55

GromNaN force-pushed the autoconfigure branch from 32ba921 to d2a7a55 Compare February 10, 2025 13:23

This was referenced Feb 25, 2025

PoC PHP file resource metadata factory Sylius/SyliusResourceBundle#983

Draft

Init resource class list factory with attributes Sylius/SyliusResourceBundle#986

Merged

soyuka mentioned this pull request Apr 5, 2025

[Symfony] ApiResource attribute auto excluded from services #7065

Closed

soyuka mentioned this pull request Apr 11, 2025

BC break from 4.1.2 if you have badly named entity? #7067

Closed

soyuka changed the base branch from 4.1 to main April 29, 2025 07:42

soyuka merged commit 4b1b94c into api-platform:main Apr 29, 2025
76 of 77 checks passed

GromNaN deleted the autoconfigure branch May 16, 2025 11:49

alexndlm pushed a commit to alexndlm/core that referenced this pull request May 26, 2025

feat(symfony): Autoconfigure classes using #[ApiResource] attribute (…

939851e

…api-platform#6943)

michaljusiega reviewed Jul 2, 2025

View reviewed changes

Uh oh!

feat(symfony): Autoconfigure classes using #[ApiResource] attribute #6943

feat(symfony): Autoconfigure classes using #[ApiResource] attribute #6943

Uh oh!

Conversation

GromNaN commented Feb 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dunglas left a comment

Choose a reason for hiding this comment

Uh oh!

soyuka commented Feb 6, 2025

Uh oh!

GromNaN commented Feb 6, 2025

Uh oh!

soyuka commented Feb 6, 2025

Uh oh!

dunglas commented Feb 6, 2025

Uh oh!

GromNaN commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GromNaN commented Feb 10, 2025

Uh oh!

GromNaN commented Feb 11, 2025

Uh oh!

GromNaN commented Mar 13, 2025

Goals

Backward-compatibility constraints:

Attributes

XML/Yaml files

Uh oh!

Nayte91 commented Apr 9, 2025

Uh oh!

soyuka commented Apr 29, 2025

Uh oh!

Uh oh!

soyuka commented Apr 29, 2025

Uh oh!

michaljusiega Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

michaljusiega Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

soyuka Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

michaljusiega Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

GromNaN Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaljusiega Aug 24, 2025

Choose a reason for hiding this comment

Uh oh!

michaljusiega Aug 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaljusiega Aug 24, 2025

Choose a reason for hiding this comment

Uh oh!

soyuka Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaljusiega Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

feat(symfony): Autoconfigure classes using `#[ApiResource]` attribute #6943

feat(symfony): Autoconfigure classes using `#[ApiResource]` attribute #6943

GromNaN commented Feb 5, 2025 •

edited

Loading

GromNaN commented Feb 6, 2025 •

edited

Loading

GromNaN Jul 7, 2025 •

edited

Loading

michaljusiega Aug 24, 2025 •

edited

Loading

soyuka Aug 25, 2025 •

edited

Loading