From 8a232e09a37feb167b000254f4de143366210805 Mon Sep 17 00:00:00 2001 From: Jaapio Date: Sun, 30 Nov 2025 21:29:58 +0100 Subject: [PATCH] Add docs for v1 to v2 migration --- docs/generics.rst | 29 ++++++++++++++++++++++++++++ docs/index.rst | 2 ++ docs/upgrade-v1-to-v2.rst | 40 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+) create mode 100644 docs/generics.rst create mode 100644 docs/upgrade-v1-to-v2.rst diff --git a/docs/generics.rst b/docs/generics.rst new file mode 100644 index 00000000..f306432f --- /dev/null +++ b/docs/generics.rst @@ -0,0 +1,29 @@ +======== +Generics +======== + +This project is capable of parsing generics notation as used by PHPStan. But it has some limitations, in regards to +PHPStan. The main difference is that PHPStan does scan your whole codebase to find out what types are used in generics, +while this library only parses the types as they are given to it. + +This means that if you use a generic type like. + +.. code:: php + + namespace MyApp; + + /** + * @template T of Item + */ + class Collection { + + /** + * @return T[] + */ + public function getItems() : array { + // ... + } + } + +The type resolver will not be able to determine what ``T`` is. In fact there is no difference between ``T`` and any other relative +used classname like ``Item``. The resolver will handle ``T`` as a normal class name. In this example it will resolve ``T`` to ``\MyApp\T``. diff --git a/docs/index.rst b/docs/index.rst index 0ff9a8b2..15129831 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,3 +15,5 @@ third party developers. index getting-started + generics + upgrade-v1-to-v2 diff --git a/docs/upgrade-v1-to-v2.rst b/docs/upgrade-v1-to-v2.rst new file mode 100644 index 00000000..4f63ad38 --- /dev/null +++ b/docs/upgrade-v1-to-v2.rst @@ -0,0 +1,40 @@ +==================== +Upgrade to Version 2 +==================== + +Version 2 of the Type Resolver introduces several breaking changes and new features. This guide will help you +upgrade your codebase to be compatible with the latest version. The usage of the TypeResolver remains the same. However, +some classes have been moved or replaced, and the minimum PHP version requirement has been raised. + +PHP Version +----------- + +Version 2 requires PHP 7.4 or higher. We have been supporting PHP 7.3 in version 1, but due to changing constraints +in our dependencies, we have had to raise the minimum PHP version. At the moment of writing this, PHP 7.3 is used by 2% +of all installations of this package according to Packagist. We believe this is a reasonable trade-off to ensure we +can continue to deliver new features and improvements. + +Moved classes +------------- + +- ``phpDocumentor\Reflection\Types\InterfaceString`` => :php:class:`phpDocumentor\Reflection\PseudoTypes\InterfaceString` +- ``phpDocumentor\Reflection\Types\ClassString`` => :php:class:`phpDocumentor\Reflection\PseudoTypes\ClassString` +- ``phpDocumentor\Reflection\Types\ArrayKey`` => :php:class:`phpDocumentor\Reflection\PseudoTypes\ArrayKey` +- ``phpDocumentor\Reflection\Types\True_`` => :php:class:`phpDocumentor\Reflection\PseudoTypes\True_` +- ``phpDocumentor\Reflection\Types\False_`` => :php:class:`phpDocumentor\Reflection\PseudoTypes\False_` + +Replaced classes +----------------- + +- ``phpDocumentor\Reflection\Types\Collection`` => :php:class:`phpDocumentor\Reflection\PseudoTypes\Generic` + +Since the introduction of generics in PHP this library was not capable of parsing them correctly. The old Collection +was blocking the use of generics. The new Generic type is a representation of generics like supported in the eco system. + +Changed implementations +----------------------- + +:php:class:`phpDocumentor\Reflection\PseudoTypes\InterfaceString`, :php:class:`phpDocumentor\Reflection\PseudoTypes\ClassString` and +:php:class:`phpDocumentor\Reflection\PseudoTypes\TraitString` are no longer returning a :php:class:`phpDocumentor\Reflection\Fqsen` since +support for generics these classes can have type arguments like any other generic. +