-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
6 changed files
with
27 additions
and
197 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,9 @@ | ||
| # Typhoon | ||
|
|
||
| The ultimate type system and reflection for PHP. | ||
|
|
||
| ## Components | ||
|
|
||
| - [Type](docs/Type.md) | ||
| - [Reflection](docs/Reflection.md) | ||
| - [TypeStringifier](docs/TypeStringifier.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,115 +1,6 @@ | ||
| # Typhoon Reflection | ||
| # [Typhoon Reflection](https://github.com/typhoon-php/typhoon/blob/0.3.x/docs/Reflection.md) | ||
|
|
||
| This library is an alternative to [native PHP Reflection](https://www.php.net/manual/en/book.reflection.php). It is: | ||
| - static, | ||
| - lazy (does not load inherited classes until you reflect properties or methods), | ||
| - [PSR-16](https://www.php-fig.org/psr/psr-16/) cacheable, | ||
| - [99% compatible with native reflection](docs/compatibility.md), | ||
| - supports most of the Psalm/PHPStan types, | ||
| - can resolve templates, | ||
| - does not create circular object references (can be safely used with [zend.enable_gc=0](https://www.php.net/manual/en/info.configuration.php#ini.zend.enable-gc)). | ||
| This repository is a readonly Typhoon monorepo subsplit. | ||
| Please, open pull requests and issues in the [main repository](https://github.com/typhoon-php/typhoon). | ||
|
|
||
| ## Installation | ||
|
|
||
| ``` | ||
| composer require typhoon/reflection jetbrains/phpstorm-stubs | ||
| ``` | ||
|
|
||
| Installing `jetbrains/phpstorm-stubs` is highly recommended. Without stubs core PHP classes are reflected via | ||
| [NativeReflector](src/NativeReflector/NativeReflector.php) that does not support phpDoc types. | ||
|
|
||
| ## Basic Usage | ||
|
|
||
| ```php | ||
| namespace My\Awesome\App; | ||
|
|
||
| use Typhoon\Reflection\TyphoonReflector; | ||
| use Typhoon\Type\types; | ||
|
|
||
| /** | ||
| * @template T | ||
| */ | ||
| final readonly class Article | ||
| { | ||
| /** | ||
| * @param non-empty-list<non-empty-string> $tags | ||
| * @param T $data | ||
| */ | ||
| public function __construct( | ||
| private array $tags, | ||
| public mixed $data, | ||
| ) {} | ||
| } | ||
|
|
||
| $reflector = TyphoonReflector::build(); | ||
| $articleReflection = $reflector->reflectClass(Article::class); | ||
|
|
||
| $tagsReflection = $articleReflection->getProperty('tags'); | ||
|
|
||
| var_dump($tagsReflection->getTyphoonType()); // object representation of non-empty-list<non-empty-string> type | ||
|
|
||
| $dataReflection = $articleReflection->getProperty('data'); | ||
|
|
||
| var_dump($dataReflection->getTyphoonType()); // object representation of T template type | ||
| ``` | ||
|
|
||
| ## Caching | ||
|
|
||
| By default, Typhoon Reflection uses in-memory LRU cache which should be enough for the majority of use cases. | ||
|
|
||
| However, if you need persistent cache, you can use any [PSR-16](https://www.php-fig.org/psr/psr-16/) implementation. We highly recommend [Typhoon OPcache](https://github.com/typhoon-php/opcache). | ||
| It stores values as php files that could be opcached. It is much faster than an average file cache implementation that uses `serialize`. | ||
|
|
||
| ```php | ||
| use Typhoon\Reflection\TyphoonReflector; | ||
| use Typhoon\OPcache\TyphoonOPcache; | ||
|
|
||
| $reflector = TyphoonReflector::build( | ||
| cache: new TyphoonOPcache('path/to/cache/dir'), | ||
| ); | ||
| ``` | ||
|
|
||
| To detect file changes during development, decorate your cache with [FreshCache](src/Cache/FreshCache.php). | ||
|
|
||
| ```php | ||
| use Typhoon\Reflection\TyphoonReflector; | ||
| use Typhoon\Reflection\Cache\FreshCache; | ||
| use Typhoon\OPcache\TyphoonOPcache; | ||
|
|
||
| $reflector = TyphoonReflector::build( | ||
| cache: new FreshCache(new TyphoonOPcache('path/to/cache/dir')), | ||
| ); | ||
| ``` | ||
|
|
||
| ## Class locators | ||
|
|
||
| By default, reflector uses: | ||
| - [ComposerClassLocator](src/ClassLocator/ComposerClassLocator.php) if composer autoloading is used, | ||
| - [PhpStormStubsClassLocator](src/ClassLocator/PhpStormStubsClassLocator.php) if `jetbrains/phpstorm-stubs` is installed, | ||
| - [NativeReflectionFileLocator](src/ClassLocator/NativeReflectionFileLocator.php) (tries to detect class file via native reflection), | ||
| - [NativeReflectionLocator](src/ClassLocator/NativeReflectionLocator.php) (returns native reflection). | ||
|
|
||
| You can implement your own locators and pass them to the `build` method: | ||
|
|
||
| ```php | ||
| use Typhoon\Reflection\ClassLocator; | ||
| use Typhoon\Reflection\ClassLocator\ClassLocators; | ||
| use Typhoon\Reflection\TyphoonReflector; | ||
|
|
||
| final class MyClassLocator implements ClassLocator | ||
| { | ||
| // ... | ||
| } | ||
|
|
||
| $reflector = TyphoonReflector::build( | ||
| classLocator: new ClassLocators([ | ||
| new MyClassLocator(), | ||
| TyphoonReflector::defaultClassLocator(), | ||
| ]), | ||
| ); | ||
| ``` | ||
|
|
||
| ## TODO | ||
|
|
||
| - [ ] enums, cases | ||
| - [ ] functions | ||
| Read [documentation](https://github.com/typhoon-php/typhoon/blob/0.3.x/docs/Reflection.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,6 @@ | ||
| # Typhoon Type | ||
| # [Typhoon Type](https://github.com/typhoon-php/typhoon/blob/0.3.x/docs/Type.md) | ||
|
|
||
| Collection of value objects that represent the extended PHP type system. | ||
| All the types are inspired by popular PHP static analysis tools: [Psalm](https://psalm.dev/) and [PHPStan](https://phpstan.org/). | ||
| This repository is a readonly Typhoon monorepo subsplit. | ||
| Please, open pull requests and issues in the [main repository](https://github.com/typhoon-php/typhoon). | ||
|
|
||
| This library will never have any dependencies. Once full and stable, it might be proposed as a [PSR](https://www.php-fig.org/psr/) or [PER](https://www.php-fig.org/per/). | ||
|
|
||
| Please, note that this is a low-level API for static analysers and reflectors. It's not designed for convenient general usage in a project. | ||
| For that purpose we plan to release a special package. | ||
|
|
||
| ## Installation | ||
|
|
||
| ``` | ||
| composer require typhoon/type | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| ```php | ||
| use Typhoon\Type\types; | ||
|
|
||
| /** | ||
| * Equivalent to type array{ | ||
| * a: non-empty-list, | ||
| * b?: int|float, | ||
| * c: Traversable<numeric-string, false>, | ||
| * d: callable(PDO::*, TSend:Generator=, scalar...): void, | ||
| * ... | ||
| * } | ||
| */ | ||
| $type = types::arrayShape([ | ||
| 'a' => types::nonEmptyString, | ||
| 'b' => types::arrayElement(types::union(types::int, types::float), optional: true), | ||
| 'c' => types::object(Traversable::class, types::numericString, types::false), | ||
| 'd' => types::callable( | ||
| parameters: [ | ||
| types::classConstant(types::object(PDO::class), '*'), | ||
| types::param(types::template('TSend', types::atClass(Generator::class)), hasDefault: true), | ||
| types::param(types::scalar, variadic: true), | ||
| ], | ||
| return: types::void, | ||
| ), | ||
| ], sealed: false); | ||
| ``` | ||
| Read [documentation](https://github.com/typhoon-php/typhoon/blob/0.3.x/docs/Type.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,34 +1,6 @@ | ||
| # Typhoon Type Stringifier | ||
| # [Typhoon Type Stringifier](https://github.com/typhoon-php/typhoon/blob/0.3.x/docs/TypeStringifier.md) | ||
|
|
||
| ## Installation | ||
| This repository is a readonly Typhoon monorepo subsplit. | ||
| Please, open pull requests and issues in the [main repository](https://github.com/typhoon-php/typhoon). | ||
|
|
||
| ``` | ||
| composer require typhoon/type-stringifier | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| ```php | ||
| use Typhoon\Type\types; | ||
| use function Typhoon\TypeStringifier\stringify; | ||
|
|
||
| echo stringify( | ||
| types::arrayShape([ | ||
| 'a' => types::nonEmptyString, | ||
| 'b' => types::arrayElement(types::union(types::int, types::float), optional: true), | ||
| 'c' => types::object(Traversable::class, types::numericString, types::false), | ||
| 'd' => types::callable( | ||
| parameters: [ | ||
| types::classConstant(types::object(PDO::class), '*'), | ||
| types::param(types::template('TSend', types::atClass(Generator::class)), hasDefault: true), | ||
| types::param(types::scalar, variadic: true), | ||
| ], | ||
| return: types::void, | ||
| ), | ||
| ], sealed: false), | ||
| ); | ||
| ``` | ||
|
|
||
| ``` | ||
| array{a: non-empty-string, b?: int|float, c: Traversable<numeric-string, false>, d: callable(PDO::*, TSend:Generator=, bool|int|float|string...): void, ...} | ||
| ``` | ||
| Read [documentation](https://github.com/typhoon-php/typhoon/blob/0.3.x/docs/TypeStringifier.md). |