feature #52510 [TypeInfo] Introduce component (mtarld)

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

Author: fabpot

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

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');

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>

Resources/config/type_info.php

@@ -0,0 +1,50 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * 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')])
+    ;
+};

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),
             ],

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' => [

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,
+    ],
+]);

Tests/DependencyInjection/Fixtures/xml/full.xml

@@ -40,5 +40,6 @@
             </framework:default-context>
         </framework:serializer>
         <framework:property-info />
+        <framework:type-info />
     </framework:config>
 </container>

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>

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: