Skip to content

[TypeInfo] Add documentation #19554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 2, 2024
Merged

[TypeInfo] Add documentation #19554

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions components/type_info.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
The TypeInfo Component
======================

The TypeInfo component extracts PHP types information. It aims to:

- 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).

.. caution::

This component is :doc:`experimental </contributing/code/experimental>` and could be changed at any time
without prior notice.

Installation
------------

.. code-block:: terminal

$ composer require symfony/type-info

.. include:: /components/require_autoload.rst.inc

Usage
-----

This component will gives you a :class:`Symfony\\Component\\TypeInfo\\Type` object that represents
the PHP type of whatever you builded or asked to resolve.

There are two ways to use this component. First one is to create a type manually thanks
to :class:`Symfony\\Component\\TypeInfo\\Type` static methods as following::

use Symfony\Component\TypeInfo\Type;

Type::int();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand the examples of this block. What are we building? Is this to create something? To check something? How can I use this in a Symfony app? Thanks.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a component you will use in a Symfony app. This is a component made for other components or for libraries to use.

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


Second way to use TypeInfo is to resolve a type based on reflection or a simple string::

use Symfony\Component\TypeInfo\Type;
use Symfony\Component\TypeInfo\TypeResolver\TypeResolver;

// Instantiate a new resolver
$typeResolver = TypeResolver::create();

// Then resolve types for any subject
$typeResolver->resolve(new \ReflectionProperty(Dummy::class, 'id')); // returns an "int" Type instance
$typeResolver->resolve('bool'); // returns a "bool" Type instance
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example is not very clear because some reader won't make the connection and don't know that 'bool' here refers to a boolean property of some class.

I think we need to create a simple class first with the needed properties ... and then show the code needed to introspect the type information.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's kinda complex because it's not something designed to use "as it is" or only for very specific cases.
I tried to explain a bit better how raw string resolving works and what it is used for (basically phpDoc).
Does it help more to understand ?


// Types can be instantiated thanks to static factories
$type = Type::list(Type::nullable(Type::bool()));

// Type instances have several helper methods
$type->getBaseType() // returns an "array" Type instance
$type->getCollectionKeyType(); // returns an "int" Type instance

Check failure on line 62 in components/type_info.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[PHP syntax] Syntax error, unexpected T_VARIABLE
$type->getCollectionValueType()->isNullable(); // returns true

Each of this rows will return you a Type instance that will corresponds to whatever static method you used to build it.
We also can resolve a type from a string like we can see in this example with the `'bool'` parameter it is mostly
designed that way so we can give TypeInfo a string from whatever was extracted from existing phpDoc within PropertyInfo.

.. note::

To support raw string resolving, you need to install ``phpstan/phpdoc-parser`` package.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't fully understand what "raw string resolving" means here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see #19554 (comment) for more details, but "raw string resolving" means you're using the resolver with a string. It is mostly designed to handle phpDoc

Loading