Releases · Roave/BetterReflection

Merry Christmas! 🎄 🎅

Major version, major work

This release is a new major version of roave/better-reflection, containing
over 600 commits, 163 pull requests, and more than 400 reviews, provided (mostly,
but not exclusively) by:

Thank you all: your thankless work means a lot.

Most relevant changes

The biggest improvements in this release are:

full support for php:~8.0.12
full support for php:~8.1.0
dropped support for php:<8.0.12
better ergonomics thanks to a new unified new \Roave\BetterReflection\BetterReflection()
entry-point (if you do not know where to start, when using this library)
major performance and memory efficiency advancement
type inference improvements: the library now passes all vimeo/psalm
and phpstan/phpstan type checks
ability to reflect symbols defined via class_alias()
better core reflection symbols thanks to jetbrains/phpstorm-stubs:2021.3
and improved internal stub parsing mechanisms.

Language version support

Because of the incredible amount of tiny (yet high impact) backwards incompatible breakages
in php itself, we had to completely cut compatibility
between php:^7.4 and this library: a major version increase was required to support PHP 8.0,
and it is likely that this will happen again with new backwards-incompatible changes in PHP 8.2
and other future language versions.

Supporting both PHP 7.4 and PHP 8.0 was not feasibly possible without a dedicated budget for
the project: we hope that the improvements will help the ecosystem grow, and move to newer
versions of the language as soon as possible.

We may re-consider this approach, should patronage allow for full-time work on this library.

Breaking changes

If you extend or implement classes or interfaces of this library, we strongly endorse to
run vimeo/psalm or phpstan/phpstan on your codebase, to identify possibly breakage points.

Most notable breaking changes since 4.12.0:

Better reflector API

Following reflectors were merged into a single Roave\BetterReflection\Reflector\Reflector interface:

Roave\BetterReflection\Reflector\ClassReflector
Roave\BetterReflection\Reflector\FunctionReflector
Roave\BetterReflection\Reflector\ConstantReflector

Where you previously created a specific reflector, you would now use a new \Roave\BetterReflection\Reflector\DefaultReflector(...),
or rely on the default (new \Roave\BetterReflection\BetterReflection())->reflector() factory method.

Monkey-patching support removed

While BetterReflection 4.x advertised "monkey-patching" support, as in "modifying reflection symbols before they
are loaded by PHP", this functionality was too superficial, and supporting it fully would have required major
increase of the API surface of the library.

In order to focus our efforts on compatibility with core reflection, and support of newer PHP versions, we decided
to keep the library at what it does best: finding and reflecting code.

Therefore, all support for monkey-patching code has been removed: BetterReflection can still give you the AST
and source locations for your code, but changing and writing to it is now up to you, and the abstraction that
you prefer to use to do so.

DocBlock parsing removed

In 2020 and 2021, the detail in type declarations increased a lot, thanks to phpstan/phpstan and vimeo/psalm
pushing the ecosystem towards a more type-safe future.

DocBlock types now include generic types, purity markers,
inheritance refinements and cross-file references.

We can't really keep up with it (due to the ever-evolving standard) and the type parsing support that we provided
so far is insufficient to keep up with modern docBlock-based type definitions.

Therefore, DocBlock support has been completely removed: this library will limit itself to providing the
DocBlock contents, but without interpreting them.

Better types for reflection functions and types

Roave\BetterReflection\Reflection\ReflectionFunctionAbstract is now a trait: most methods that
used to accept it now require a union type of ReflectionFunction|ReflectionMethod to operate.

The same applies to Roave\BetterReflection\Reflection\ReflectionType: most type signatures in the
library will not operate with (or return) a ReflectionType, but instead a union type such as
NamedType|UnionType|IntersectionType|null, to better represent the limits of what this library
can understand, and to better highlight future backwards-incompatible changes.

Constant expressions can now yield `object`s and resources

Before PHP 8.0, it was not possible to put non-scalar values in const and constant() expressions,
at least from userland. This changed recently, and BetterReflection had to adapt too.

Evaluating AST expressions, such as when calling ReflectionConstant#getValue(), can now produce mixed
values, whereas only scalar and array values supported before

List of BC breaks

This is a list of detected BC breaks, generated via roave/backward-compatibility-check:6.0.x-dev.
It is a long list, but it is useful as a reference, should you encounter specific breakages in particular
methods that you rely upon.

[BC] REMOVED: Class Roave\BetterReflection\TypesFinder\ResolveTypes has been deleted
[BC] REMOVED: Class Roave\BetterReflection\TypesFinder\PhpDocumentor\NamespaceNodeToReflectionTypeContext has been deleted
[BC] REMOVED: Class Roave\BetterReflection\TypesFinder\FindReturnType has been deleted
[BC] REMOVED: Class Roave\BetterReflection\TypesFinder\FindPropertyType has been deleted
[BC] REMOVED: Class Roave\BetterReflection\TypesFinder\FindParameterType has been deleted
[BC] REMOVED: Method Roave\BetterReflection\BetterReflection#classReflector() was removed
[BC] REMOVED: Method Roave\BetterReflection\BetterReflection#functionReflector() was removed
[BC] REMOVED: Method Roave\BetterReflection\BetterReflection#constantReflector() was removed
[BC] CHANGED: Roave\BetterReflection\SourceLocator\Located\InternalLocatedSource was marked "@internal"
[BC] CHANGED: The number of required arguments for Roave\BetterReflection\SourceLocator\Located\InternalLocatedSource#__construct() increased from 2 to 3
[BC] CHANGED: Parameter 1 of Roave\BetterReflection\SourceLocator\Located\InternalLocatedSource#__construct() changed name from extensionName to name
[BC] CHANGED: Roave\BetterReflection\SourceLocator\Located\EvaledLocatedSource was marked "@internal"
[BC] CHANGED: The number of required arguments for Roave\BetterReflection\SourceLocator\Located\EvaledLocatedSource#__construct() increased from 1 to 2
[BC] CHANGED: The parameter $nonSplFileInfo of Roave\BetterReflection\SourceLocator\Exception\InvalidFileInfo::fromNonSplFileInfo() changed from no type to mixed
[BC] REMOVED: Method Roave\BetterReflection\SourceLocator\Exception\InvalidDirectory::fromNonStringValue() was removed
[BC] ADDED: Method reflectClass() was added to interface Roave\BetterReflection\Reflector\Reflector
[BC] ADDED: Method reflectAllClasses() was added to interface Roave\BetterReflection\Reflector\Reflector
[BC] ADDED: Method reflectFunction() was added to interface Roave\BetterReflection\Reflector\Reflector
[BC] ADDED: Method reflectAllFunctions() was added to interface Roave\BetterReflection\Reflector\Reflector
[BC] ADDED: Method reflectConstant() was added to interface Roave\BetterReflection\Reflector\Reflector
[BC] ADDED: Method reflectAllConstants() was added to interface Roave\BetterReflection\Reflector\Reflector
[BC] REMOVED: Method Roave\BetterReflection\Reflector\Reflector#reflect() was removed
[BC] REMOVED: Class Roave\BetterReflection\Reflector\FunctionReflector has been deleted
[BC] REMOVED: Class Roave\BetterReflection\Reflector\ConstantReflector has been deleted
[BC] REMOVED: Class Roave\BetterReflection\Reflector\ClassReflector has been deleted
[BC] CHANGED: Class Roave\BetterReflection\Reflection\ReflectionType became abstract
[BC] REMOVED: Method Roave\BetterReflection\Reflection\ReflectionType::createFromTypeAndReflector() was removed
[BC] REMOVED: Method Roave\BetterReflection\Reflection\ReflectionType#isBuiltin() was removed
[BC] REMOVED: Method Roave\BetterReflection\Reflection\ReflectionType#targetReflectionClass() was removed
[BC] REMOVED: Method Roave\BetterReflection\Reflection\ReflectionType#getName() was removed
[BC] CHANGED: Method allowsNull() of class Roave\BetterReflection\Reflection\ReflectionType changed from concrete to abstract
[BC] CHANGED: Method __toString() of class Roave\BetterReflection\Reflection\ReflectionType changed from concrete to abstract
[BC] REMOVED: Method Roave\BetterReflection\Reflection\ReflectionProperty#setVisibility() was removed
[BC] REMOVED: Method Roave\BetterReflection\Reflection\ReflectionProperty#getDocBlockTypeStrings() was removed
[BC] REMOVED: Method Roave\BetterReflection\Reflection\ReflectionProperty#getDocBloc...