Skip to content
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.

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

Removed doc blocks parsing support #900

Merged
merged 3 commits into from
Dec 5, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 0 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ Better Reflection is a reflection API that aims to improve and provide more feat

* You can reflect on classes that are not already loaded, without loading them
* Ability to reflect on classes directly from a string of PHP code
* Better Reflection analyses the DocBlocks (using [phpdocumentor/type-resolver](https://github.com/phpDocumentor/TypeResolver))
* Reflecting directly on closures
* Ability to extract AST from methods and functions
* Ability to return AST representation of a class or function
Expand Down
93 changes: 50 additions & 43 deletions UPGRADE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,26 @@ or backwards compatibility (BC) breakages occur.
## 5.0.0

### BC Breaks
* Doc block parsing has been removed:
* `\Roave\BetterReflection\Reflection\ReflectionMethod::getDocBlockReturnTypes()`
* `\Roave\BetterReflection\Reflection\ReflectionFunction::getDocBlockReturnTypes()`
* `\Roave\BetterReflection\Reflection\ReflectionParameter::getDocBlockTypes()`
* `\Roave\BetterReflection\Reflection\ReflectionParameter::getDocBlockTypeStrings()`
* `\Roave\BetterReflection\Reflection\ReflectionProperty::getDocBlockTypes()`
* `\Roave\BetterReflection\Reflection\ReflectionProperty::getDocBlockTypeStrings()`
* Method `\Roave\BetterReflection\Identifier\IdentifierType::isMatchingReflector()` has been removed.
* All adapters are `final`
* `ClassReflector`, `FunctionReflector` and `ConstantReflector` have been removed. Use `DefaultReflector` to reflect all types.
* Removed support for PHP4 style constructors
* Adapters don't have `::export()` method anymore because these methods were removed from PHP. These methods have been removed:
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionClass::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionFunction::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionMethod::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionObject::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionParameter::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionProperty::export()`
* Casting to string is compatible with PHP:
* `string or NULL` is now `?string`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionClass::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionFunction::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionMethod::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionObject::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionParameter::export()`
* `\Roave\BetterReflection\Reflection\Adapter\ReflectionProperty::export()`
* Casting to string is compatible with PHP:
* `string or NULL` is now `?string`
* `boolean` is now `bool`
* `integer` is now `int`
* properties types are exported
Expand Down Expand Up @@ -46,41 +53,41 @@ or backwards compatibility (BC) breakages occur.

### BC breaks

* Method `Roave\BetterReflection\Reflection\ReflectionType::createFromType()` has been removed, use
* Method `Roave\BetterReflection\Reflection\ReflectionType::createFromType()` has been removed, use
`Roave\BetterReflection\Reflection\ReflectionType::createFromTypeAndReflector()` instead.
* Method `Roave\BetterReflection\Reflection\Adapter\ReflectionClass#getProperty()` throws an exception when a property
* Method `Roave\BetterReflection\Reflection\Adapter\ReflectionClass#getProperty()` throws an exception when a property
does not exist (to be compatible with core reflection).
* Method `Roave\BetterReflection\Reflection\Adapter\ReflectionObject#getProperty()` throws an exception when a property
* Method `Roave\BetterReflection\Reflection\Adapter\ReflectionObject#getProperty()` throws an exception when a property
does not exist (to be compatible with core reflection).

## 2.0.0

### Namespace change

The base namespace of the library changed from `BetterReflection` to `Roave\BetterReflection`. You may search for
The base namespace of the library changed from `BetterReflection` to `Roave\BetterReflection`. You may search for
usages of the previous namespace with following regular expressions:

* `/\s*use\s+(\\)?BetterReflection/`
* `/[^A-Za-z0-9]+(\\)?BetterReflection/`

The found imports should be replaced with `Roave\BetterReflection` imports.

### PHP Version requirement raised to PHP 7.1.* and PHP 7.2.*

Due to the complexity of maintaining compatibility with multiple PHP runtime environments and reflection API changes,
Due to the complexity of maintaining compatibility with multiple PHP runtime environments and reflection API changes,
the library now only supports PHP 7.1.x and PHP 7.2.x

### Source locators now require additional dependencies

Due to major design and performance improvements, many of the existing
Due to major design and performance improvements, many of the existing
`Roave\BetterReflection\SourceLocator\Type\SourceLocator` implementations now require you to pass in more parameters.

Following classes have a changed constructor signature:

* `Roave\BetterReflection\SourceLocator\Type\AbstractSourceLocator`
* `Roave\BetterReflection\SourceLocator\Type\AutoloadSourceLocator`

In order to comply with the new constructor signatures, you can use the newly introduced
In order to comply with the new constructor signatures, you can use the newly introduced
`Roave\BetterReflection\BetterReflection` kernel object:

```php
Expand Down Expand Up @@ -115,12 +122,12 @@ also need to adapt to the parent constructor signature.

### `BetterReflection\Reflection\Exception\NotAString` removed

The `BetterReflection\Reflection\Exception\NotAString` exception was removed, as we now rely on PHP 7's
The `BetterReflection\Reflection\Exception\NotAString` exception was removed, as we now rely on PHP 7's
`declare(strict_types=1)`

### `Roave\BetterReflection\Util\FindReflectionOnLine` constructor changed

`Roave\BetterReflection\Util\FindReflectionOnLine` now requires additional parameters. It is advisable to use the
`Roave\BetterReflection\Util\FindReflectionOnLine` now requires additional parameters. It is advisable to use the
`Roave\BetterReflection\BetterReflection` kernel to get an instance of this class instead:

```php
Expand All @@ -135,7 +142,7 @@ $findReflectionOnLine = (new BetterReflection())->findReflectionsOnLine();

`Roave\BetterReflection\Identifier\Identifier::__construct()` now requires the `$name` parameter to be a `string`.

A `BetterReflection\Reflection\Exception\NotAString` will no longer be thrown, while you will get a `TypeError`
A `BetterReflection\Reflection\Exception\NotAString` will no longer be thrown, while you will get a `TypeError`
instead, should you not comply with this signature at call time.


Expand All @@ -145,15 +152,15 @@ The internal `Roave\BetterReflection\NodeCompiler` class now requires a second m

### `Roave\BetterReflection\Reflector\Reflector#reflect()` interface changed

The `Roave\BetterReflection\Reflector\Reflector#reflect()` now requires a `string` argument for `$identifierName`. You
The `Roave\BetterReflection\Reflector\Reflector#reflect()` now requires a `string` argument for `$identifierName`. You
will need to change your own implementations of the interface.

### `BetterReflection\Reflection\ReflectionParameter#getDefaultValueAsString()` removed

`BetterReflection\Reflection\ReflectionParameter#getDefaultValueAsString()` was removed. This method was providing some
`BetterReflection\Reflection\ReflectionParameter#getDefaultValueAsString()` was removed. This method was providing some
sort of serialization of internal reflection data, and it opens possibilities for security issues if mishandled.

The equivalent replacement is to manually call `var_export($value, true)` instead, assuming that you know its intended
The equivalent replacement is to manually call `var_export($value, true)` instead, assuming that you know its intended
usage context:

```php
Expand All @@ -176,26 +183,26 @@ echo var_export($defaultValue, true);

### `BetterReflection\TypesFinder\FindTypeFromAst` was removed

The `BetterReflection\TypesFinder\FindTypeFromAst` utility was removed, as all AST nodes used by `BetterReflection` are
now processed through a `PhpParser\NodeVisitor\NameResolver` visitor, which guarantees that the FQCN of the symbol is
The `BetterReflection\TypesFinder\FindTypeFromAst` utility was removed, as all AST nodes used by `BetterReflection` are
now processed through a `PhpParser\NodeVisitor\NameResolver` visitor, which guarantees that the FQCN of the symbol is
always available.

This change also allowed for massive performance improvement, as fewer repeated parsing operations have to be performed
This change also allowed for massive performance improvement, as fewer repeated parsing operations have to be performed
in order to discover node types.

### `BetterReflection\Reflection\ReflectionParameter#getTypeHint()` was removed

The `BetterReflection\Reflection\ReflectionParameter#getTypeHint()` was dropped, favoring just
The `BetterReflection\Reflection\ReflectionParameter#getTypeHint()` was dropped, favoring just
`BetterReflection\Reflection\ReflectionParameter#getType()` instead.

### `BetterReflection\Reflection\ReflectionParameter#setType()` now requires a `string`

The `BetterReflection\Reflection\ReflectionParameter#setType()` method now requires a `string` argument to be passed to
The `BetterReflection\Reflection\ReflectionParameter#setType()` method now requires a `string` argument to be passed to
it. The type will be detected from the given string.

### `BetterReflection\Reflection\ReflectionType` now works with `string` type definitions

The `BetterReflection\Reflection\ReflectionType` object used to work with `phpDocumentor` implementation details, but
The `BetterReflection\Reflection\ReflectionType` object used to work with `phpDocumentor` implementation details, but
is now fully independent and only relying on `string` type definitions. Therefore:

* `ReflectionType::getTypeObject()` was removed
Expand All @@ -204,18 +211,18 @@ is now fully independent and only relying on `string` type definitions. Therefor

### `BetterReflection\Reflection\ReflectionFunctionAbstract#setReturnType()` now requires a `string`

The `BetterReflection\Reflection\ReflectionFunctionAbstract#setReturnType()` method now requires a `string` argument to
The `BetterReflection\Reflection\ReflectionFunctionAbstract#setReturnType()` method now requires a `string` argument to
be passed to it. The type will be detected from the given string.

### `Roave\BetterReflection\SourceLocator\Reflection\SourceStubber` now works with core `ReflectionClass`

The `Roave\BetterReflection\SourceLocator\Reflection\SourceStubber` is now capable of working with just
`ReflectionClass` instances from PHP core: it is no longer required to use `Zend\Code` instances, but the type hints
The `Roave\BetterReflection\SourceLocator\Reflection\SourceStubber` is now capable of working with just
`ReflectionClass` instances from PHP core: it is no longer required to use `Zend\Code` instances, but the type hints
also changed accordingly.

### `Roave\BetterReflection\Reflector\ClassReflector::buildDefaultReflector()` dropped

Since the `Roave\BetterReflection\BetterReflection` kernel was introduced,
Since the `Roave\BetterReflection\BetterReflection` kernel was introduced,
`Roave\BetterReflection\Reflector\ClassReflector::buildDefaultReflector()` was removed. The equivalent API is following:

```php
Expand All @@ -228,15 +235,15 @@ $reflector = (new BetterReflection())->classReflector();

### `Roave\BetterReflection\Reflection\Exception\PropertyNotPublic` dropped

The `Roave\BetterReflection\Reflection\Exception\PropertyNotPublic` was thrown when a non-accessible reflection
property is being read or written to. Since this is "better" reflection, there is no need for calling anything like
`setAccessible` on a `Roave\BetterReflection\Reflection\ReflectionProperty` instance. All properties are directly
The `Roave\BetterReflection\Reflection\Exception\PropertyNotPublic` was thrown when a non-accessible reflection
property is being read or written to. Since this is "better" reflection, there is no need for calling anything like
`setAccessible` on a `Roave\BetterReflection\Reflection\ReflectionProperty` instance. All properties are directly
accessible, even if `private`, `protected` or dynamically defined.

### `Roave\BetterReflection\Reflector\FunctionReflector` constructor changed

The constructor of `Roave\BetterReflection\Reflector\FunctionReflector` changed in its required parameters. For generic
`BetterReflection` usage, it is advisable to obtain a `Roave\BetterReflection\Reflector\FunctionReflector` from the
The constructor of `Roave\BetterReflection\Reflector\FunctionReflector` changed in its required parameters. For generic
`BetterReflection` usage, it is advisable to obtain a `Roave\BetterReflection\Reflector\FunctionReflector` from the
`Roave\BetterReflection\BetterReflection` kernel:

```php
Expand All @@ -249,8 +256,8 @@ $reflector = (new BetterReflection())->functionReflector();

### `Roave\BetterReflection\SourceLocator\Ast\Locator` constructor changed

The constructor of `Roave\BetterReflection\SourceLocator\Ast\Locator` changed in its required parameters. For generic
`BetterReflection` usage, it is advisable to obtain a `Roave\BetterReflection\SourceLocator\Ast\Locator` from the
The constructor of `Roave\BetterReflection\SourceLocator\Ast\Locator` changed in its required parameters. For generic
`BetterReflection` usage, it is advisable to obtain a `Roave\BetterReflection\SourceLocator\Ast\Locator` from the
`Roave\BetterReflection\BetterReflection` kernel:

```php
Expand All @@ -268,11 +275,11 @@ Due to performance and type introspection requirements, the following methods ch
* `Roave\BetterReflection\Reflection\ReflectionParameter::createFromNode()`
* `Roave\BetterReflection\Reflection\ReflectionProperty::createFromNode()`

It is advisable to not call these methods directly, as they are likely to change in future as well. Instead, please use
It is advisable to not call these methods directly, as they are likely to change in future as well. Instead, please use
a corresponding `Roave\BetterReflection\Reflector\Reflector` object to instantiate them.

### `Roave\BetterReflection\SourceLocator\Located\InternalLocatedSource` constructor changed

In order to aid in detecting the source of a located internal class or function, the
`Roave\BetterReflection\SourceLocator\Located\InternalLocatedSource` now has an additional mandatory `$extensionName`
In order to aid in detecting the source of a located internal class or function, the
`Roave\BetterReflection\SourceLocator\Located\InternalLocatedSource` now has an additional mandatory `$extensionName`
parameter.
2 changes: 0 additions & 2 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@
"ext-json": "*",
"jetbrains/phpstorm-stubs": "2021.3",
"nikic/php-parser": "^4.13.2",
"phpdocumentor/reflection-docblock": "^5.3.0",
"phpdocumentor/type-resolver": "^1.5.0",
"roave/signature": "^1.5"
},
"config": {
Expand Down
Loading