feature #52510 [TypeInfo] Introduce component (mtarld)

fabpot · fabpot · commit 6ccc82d3b0c7 · 2024-02-03T17:29:52.000+01:00
This PR was merged into the 7.1 branch. Discussion ---------- [TypeInfo] Introduce component | Q | A | ------------- | --- | Branch? | 7.1 | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | | License | MIT | Doc PR | TODO Introducing the brand new `TypeInfo` component This work has been done with `@Korbeil` ## State of the art ### Scope of the current `Symfony\Component\PropertyInfo\Type` class Nowadays, when we need to work with types within Symfony, we have to use the `Type` class of the `PropertyInfo` component. But what if we want to represent the type of a function's return type? We still can use that `Type` class, but it won't make much sense as the `Symfony\Component\PropertyInfo\Type` is closely related to a property (as the namespace suggests). Plus, when we need to extract types, we must use the `PropertyTypeExtractorInterface` service: ```php readonly class Person { public function __construct( public string $firstName, ) { } } // will return an array with a single Type object representing a string $types = $this->propertyTypeExtractor->getTypes(Person::class, 'firstName'); ``` Therefore, type retrieval in Symfony is limited to properties only. ### `Symfony\Component\PropertyInfo\Type`'s conceptual limitations On top of that, there is a clear limitation of the current `Type` class where unions, intersections or even generics can't be properly described. The actual workaround is that the `PropertyTypeExtractorInterface` is returning an array of `Type`, which can be interpreted as a union type. ## The `TypeInfo` component All these reasons bring us to create the `TypeInfo` component. The aim here is to address these issues and: - Have a powerful `Type` definition that can handle union, intersections, and generics (and could be even more extended) - Being able to get types from anything, such as properties, method arguments, return types, and raw strings (and can also be extended). ### `Type` classes To ensure a powerful `Type` definition, we defined multiple classes: ![Type classes](https://i.imgur.com/Exs5gcY.png) The base `Type` class is an abstract one, so you'll always need to use one of the classes that inherit it. Other types of classes are kinda self-explanatory. ### Type resolving In the `TypeInfo` component, we added a `TypeResolverInterface`, and several implementations which allow developers to get a `Type` from many things: - `ReflectionParameterTypeResolver` to resolve a function/method parameter type thanks to reflection - `ReflectionPropertyTypeResolver` to resolve a property type thanks to reflection - `ReflectionReturnTypeResolver` to resolve a function/method return type thanks to reflection - `ReflectionTypeResolver` to resolve a `ReflectionNamedType` - `StringTypeResolver` to resolve a type string representation. This can greatly work in combination with PHP documentation. > That resolver will only be available if the `phpstan/phpdoc-parser` package is installed. - `ChainTypeResolver` to iterate over resolvers and to return a type as soon as a nested resolver succeeds in resolving. ### Type Creation We also improved a lot the DX for the type creation with factories: ```php <?php use Symfony\Component\TypeInfo\Type; Type::int(); Type::nullable(Type::string()); Type::generic(Type::object(Collection::class), Type::int()); Type::list(Type::bool()); Type::intersection(Type::object(\Stringable::class), Type::object(\Iterator::class)); // Many others are available and can be // found in Symfony\Component\TypeInfo\TypeFactoryTrait ``` ### Upgrade path This PR only introduces the `TypeInfo` component, but another one (which is already ready) will deprecate the `Symfony\Component\PropertyInfo\Type` in favor of `Symfony\Component\TypeInfo\Type`. Commits ------- 6de7d7df0d [TypeInfo] Introduce component
diff --git a/DependencyInjection/Configuration.php b/DependencyInjection/Configuration.php
@@ -44,6 +44,7 @@
 use Symfony\Component\Serializer\Encoder\JsonDecode;
 use Symfony\Component\Serializer\Serializer;
 use Symfony\Component\Translation\Translator;
+use Symfony\Component\TypeInfo\Type;
 use Symfony\Component\Uid\Factory\UuidFactory;
 use Symfony\Component\Validator\Validation;
 use Symfony\Component\Webhook\Controller\WebhookController;
@@ -164,6 +165,7 @@ public function getConfigTreeBuilder(): TreeBuilder
         $this->addAnnotationsSection($rootNode);
         $this->addSerializerSection($rootNode, $enableIfStandalone);
         $this->addPropertyAccessSection($rootNode, $willBeAvailable);
+        $this->addTypeInfoSection($rootNode, $enableIfStandalone);
         $this->addPropertyInfoSection($rootNode, $enableIfStandalone);
         $this->addCacheSection($rootNode, $willBeAvailable);
         $this->addPhpErrorsSection($rootNode);
@@ -1161,6 +1163,18 @@ private function addPropertyInfoSection(ArrayNodeDefinition $rootNode, callable
         ;
     }
 
+    private function addTypeInfoSection(ArrayNodeDefinition $rootNode, callable $enableIfStandalone): void
+    {
+        $rootNode
+            ->children()
+                ->arrayNode('type_info')
+                    ->info('Type info configuration')
+                    ->{$enableIfStandalone('symfony/type-info', Type::class)}()
+                ->end()
+            ->end()
+        ;
+    }
+
     private function addCacheSection(ArrayNodeDefinition $rootNode, callable $willBeAvailable): void
     {
         $rootNode
diff --git a/DependencyInjection/FrameworkExtension.php b/DependencyInjection/FrameworkExtension.php
@@ -53,6 +53,7 @@
 use Symfony\Component\Console\Debug\CliRequest;
 use Symfony\Component\Console\Messenger\RunCommandMessageHandler;
 use Symfony\Component\DependencyInjection\Alias;
+use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;
 use Symfony\Component\DependencyInjection\ChildDefinition;
 use Symfony\Component\DependencyInjection\Compiler\ServiceLocatorTagPass;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -168,6 +169,8 @@
 use Symfony\Component\Translation\LocaleSwitcher;
 use Symfony\Component\Translation\PseudoLocalizationTranslator;
 use Symfony\Component\Translation\Translator;
+use Symfony\Component\TypeInfo\Type;
+use Symfony\Component\TypeInfo\TypeResolver\StringTypeResolver;
 use Symfony\Component\Uid\Factory\UuidFactory;
 use Symfony\Component\Uid\UuidV4;
 use Symfony\Component\Validator\Constraints\ExpressionLanguageProvider;
@@ -390,6 +393,10 @@ public function load(array $configs, ContainerBuilder $container): void
             $container->removeDefinition('console.command.serializer_debug');
         }
 
+        if ($this->readConfigEnabled('type_info', $container, $config['type_info'])) {
+            $this->registerTypeInfoConfiguration($container, $loader);
+        }
+
         if ($propertyInfoEnabled) {
             $this->registerPropertyInfoConfiguration($container, $loader);
         }
@@ -1956,6 +1963,25 @@ private function registerPropertyInfoConfiguration(ContainerBuilder $container,
         }
     }
 
+    private function registerTypeInfoConfiguration(ContainerBuilder $container, PhpFileLoader $loader): void
+    {
+        if (!class_exists(Type::class)) {
+            throw new LogicException('TypeInfo support cannot be enabled as the TypeInfo component is not installed. Try running "composer require symfony/type-info".');
+        }
+
+        $loader->load('type_info.php');
+
+        if (ContainerBuilder::willBeAvailable('phpstan/phpdoc-parser', PhpDocParser::class, ['symfony/framework-bundle', 'symfony/type-info'])) {
+            $container->register('type_info.resolver.string', StringTypeResolver::class);
+
+            /** @var ServiceLocatorArgument $resolversLocator */
+            $resolversLocator = $container->getDefinition('type_info.resolver')->getArgument(0);
+            $resolversLocator->setValues($resolversLocator->getValues() + [
+                'string' => new Reference('type_info.resolver.string'),
+            ]);
+        }
+    }
+
     private function registerLockConfiguration(array $config, ContainerBuilder $container, PhpFileLoader $loader): void
     {
         $loader->load('lock.php');
diff --git a/Resources/config/schema/symfony-1.0.xsd b/Resources/config/schema/symfony-1.0.xsd
@@ -27,6 +27,7 @@
             <xsd:element name="property-access" type="property_access" minOccurs="0" maxOccurs="1" />
             <xsd:element name="scheduler" type="scheduler" minOccurs="0" maxOccurs="1" />
             <xsd:element name="serializer" type="serializer" minOccurs="0" maxOccurs="1" />
+            <xsd:element name="type-info" type="type_info" minOccurs="0" maxOccurs="1" />
             <xsd:element name="property-info" type="property_info" minOccurs="0" maxOccurs="1" />
             <xsd:element name="cache" type="cache" minOccurs="0" maxOccurs="1" />
             <xsd:element name="workflow" type="workflow" minOccurs="0" maxOccurs="unbounded" />
@@ -327,6 +328,10 @@
         <xsd:attribute name="max-depth-handler" type="xsd:string" />
     </xsd:complexType>
 
+    <xsd:complexType name="type_info">
+        <xsd:attribute name="enabled" type="xsd:boolean" />
+    </xsd:complexType>
+
     <xsd:complexType name="property_info">
         <xsd:attribute name="enabled" type="xsd:boolean" />
     </xsd:complexType>
diff --git a/Resources/config/type_info.php b/Resources/config/type_info.php
@@ -0,0 +1,50 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+use Symfony\Component\TypeInfo\TypeContext\TypeContextFactory;
+use Symfony\Component\TypeInfo\TypeResolver\ReflectionParameterTypeResolver;
+use Symfony\Component\TypeInfo\TypeResolver\ReflectionPropertyTypeResolver;
+use Symfony\Component\TypeInfo\TypeResolver\ReflectionReturnTypeResolver;
+use Symfony\Component\TypeInfo\TypeResolver\ReflectionTypeResolver;
+use Symfony\Component\TypeInfo\TypeResolver\TypeResolver;
+use Symfony\Component\TypeInfo\TypeResolver\TypeResolverInterface;
+
+return static function (ContainerConfigurator $container) {
+    $container->services()
+        // type context
+        ->set('type_info.type_context_factory', TypeContextFactory::class)
+            ->args([service('type_info.resolver.string')->nullOnInvalid()])
+
+        // type resolvers
+        ->set('type_info.resolver', TypeResolver::class)
+            ->args([service_locator([
+                \ReflectionType::class => service('type_info.resolver.reflection_type'),
+                \ReflectionParameter::class => service('type_info.resolver.reflection_parameter'),
+                \ReflectionProperty::class => service('type_info.resolver.reflection_property'),
+                \ReflectionFunctionAbstract::class => service('type_info.resolver.reflection_return'),
+            ])])
+        ->alias(TypeResolverInterface::class, 'type_info.resolver')
+
+        ->set('type_info.resolver.reflection_type', ReflectionTypeResolver::class)
+            ->args([service('type_info.type_context_factory')])
+
+        ->set('type_info.resolver.reflection_parameter', ReflectionParameterTypeResolver::class)
+            ->args([service('type_info.resolver.reflection_type'), service('type_info.type_context_factory')])
+
+        ->set('type_info.resolver.reflection_property', ReflectionPropertyTypeResolver::class)
+            ->args([service('type_info.resolver.reflection_type'), service('type_info.type_context_factory')])
+
+        ->set('type_info.resolver.reflection_return', ReflectionReturnTypeResolver::class)
+            ->args([service('type_info.resolver.reflection_type'), service('type_info.type_context_factory')])
+    ;
+};
diff --git a/Tests/DependencyInjection/ConfigurationTest.php b/Tests/DependencyInjection/ConfigurationTest.php
@@ -28,6 +28,7 @@
 use Symfony\Component\RateLimiter\Policy\TokenBucketLimiter;
 use Symfony\Component\Scheduler\Messenger\SchedulerTransportFactory;
 use Symfony\Component\Serializer\Encoder\JsonDecode;
+use Symfony\Component\TypeInfo\Type;
 use Symfony\Component\Uid\Factory\UuidFactory;
 
 class ConfigurationTest extends TestCase
@@ -664,6 +665,9 @@ protected static function getBundleDefaultConfig()
                 'throw_exception_on_invalid_index' => false,
                 'throw_exception_on_invalid_property_path' => true,
             ],
+            'type_info' => [
+                'enabled' => !class_exists(FullStack::class) && class_exists(Type::class),
+            ],
             'property_info' => [
                 'enabled' => !class_exists(FullStack::class),
             ],
diff --git a/Tests/DependencyInjection/Fixtures/php/full.php b/Tests/DependencyInjection/Fixtures/php/full.php
@@ -70,6 +70,7 @@
         'default_context' => ['enable_max_depth' => true],
     ],
     'property_info' => true,
+    'type_info' => true,
     'ide' => 'file%%link%%format',
     'request' => [
         'formats' => [
diff --git a/Tests/DependencyInjection/Fixtures/php/type_info.php b/Tests/DependencyInjection/Fixtures/php/type_info.php
@@ -0,0 +1,11 @@
+<?php
+
+$container->loadFromExtension('framework', [
+    'annotations' => false,
+    'http_method_override' => false,
+    'handle_all_throwables' => true,
+    'php_errors' => ['log' => true],
+    'type_info' => [
+        'enabled' => true,
+    ],
+]);
diff --git a/Tests/DependencyInjection/Fixtures/xml/full.xml b/Tests/DependencyInjection/Fixtures/xml/full.xml
@@ -40,5 +40,6 @@
             </framework:default-context>
         </framework:serializer>
         <framework:property-info />
+        <framework:type-info />
     </framework:config>
 </container>
diff --git a/Tests/DependencyInjection/Fixtures/xml/type_info.xml b/Tests/DependencyInjection/Fixtures/xml/type_info.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<container xmlns="http://symfony.com/schema/dic/services"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xmlns:framework="http://symfony.com/schema/dic/symfony"
+           xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+    <framework:config http-method-override="false" handle-all-throwables="true">
+        <framework:annotations enabled="false" />
+        <framework:php-errors log="true" />
+        <framework:type-info enabled="true" />
+    </framework:config>
+</container>
diff --git a/Tests/DependencyInjection/Fixtures/yml/full.yml b/Tests/DependencyInjection/Fixtures/yml/full.yml
@@ -59,6 +59,7 @@ framework:
          max_depth_handler:          my.max.depth.handler
          default_context:
              enable_max_depth: true
+    type_info: ~
     property_info: ~
     ide: file%%link%%format
     request:
diff --git a/Tests/DependencyInjection/Fixtures/yml/type_info.yml b/Tests/DependencyInjection/Fixtures/yml/type_info.yml
@@ -0,0 +1,8 @@
+framework:
+    annotations: false
+    http_method_override: false
+    handle_all_throwables: true
+    php_errors:
+        log: true
+    type_info:
+        enabled: true
diff --git a/Tests/DependencyInjection/FrameworkExtensionTestCase.php b/Tests/DependencyInjection/FrameworkExtensionTestCase.php
@@ -1617,6 +1617,12 @@ public function testSerializerServiceIsNotRegisteredWhenDisabled()
         $this->assertFalse($container->hasDefinition('serializer'));
     }
 
+    public function testTypeInfoEnabled()
+    {
+        $container = $this->createContainerFromFile('type_info');
+        $this->assertTrue($container->has('type_info.resolver'));
+    }
+
     public function testPropertyInfoEnabled()
     {
         $container = $this->createContainerFromFile('property_info');
diff --git a/Tests/Functional/TypeInfoTest.php b/Tests/Functional/TypeInfoTest.php
@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\Tests\Functional;
+
+use PHPStan\PhpDocParser\Parser\PhpDocParser;
+use Symfony\Bundle\FrameworkBundle\Tests\Functional\app\TypeInfo\Dummy;
+use Symfony\Component\TypeInfo\Type;
+
+class TypeInfoTest extends AbstractWebTestCase
+{
+    public function testComponent()
+    {
+        static::bootKernel(['test_case' => 'TypeInfo']);
+
+        $this->assertEquals(Type::string(), static::getContainer()->get('type_info.resolver')->resolve(new \ReflectionProperty(Dummy::class, 'name')));
+
+        if (!class_exists(PhpDocParser::class)) {
+            $this->markTestSkipped('"phpstan/phpdoc-parser" dependency is required.');
+        }
+
+        $this->assertEquals(Type::int(), static::getContainer()->get('type_info.resolver')->resolve('int'));
+    }
+}
diff --git a/Tests/Functional/app/TypeInfo/Dummy.php b/Tests/Functional/app/TypeInfo/Dummy.php
@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\Tests\Functional\app\TypeInfo;
+
+/**
+ * @author Mathias Arlaud <mathias.arlaud@gmail.com>
+ * @author Baptiste Leduc <baptiste.leduc@gmail.com>
+ */
+class Dummy
+{
+    public string $name;
+}
diff --git a/Tests/Functional/app/TypeInfo/bundles.php b/Tests/Functional/app/TypeInfo/bundles.php
@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
+use Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\TestBundle;
+
+return [
+    new FrameworkBundle(),
+    new TestBundle(),
+];
diff --git a/Tests/Functional/app/TypeInfo/config.yml b/Tests/Functional/app/TypeInfo/config.yml
@@ -0,0 +1,11 @@
+imports:
+    - { resource: ../config/default.yml }
+
+framework:
+    http_method_override: false
+    type_info: true
+
+services:
+    type_info.resolver.alias:
+        alias: type_info.resolver
+        public: true
diff --git a/composer.json b/composer.json
@@ -64,6 +64,7 @@
         "symfony/string": "^6.4|^7.0",
         "symfony/translation": "^6.4|^7.0",
         "symfony/twig-bundle": "^6.4|^7.0",
+        "symfony/type-info": "^7.1",
         "symfony/validator": "^6.4|^7.0",
         "symfony/workflow": "^6.4|^7.0",
         "symfony/yaml": "^6.4|^7.0",
