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

[GromNaN]

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

[dunglas]

Very smart! I like this.

[soyuka]

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]

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]

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]

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]

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.

[GromNaN]

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.

[GromNaN]

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]

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.