xp-framework / reflection
Reflection
Installs: 45 217
Dependents: 13
Suggesters: 0
Security: 0
Stars: 2
Watchers: 3
Forks: 0
Open Issues: 4
Requires
- php: >=7.4.0
- xp-framework/ast: ^11.0 | ^10.0 | ^9.0 | ^8.0 | ^7.6
- xp-framework/core: ^12.0 | ^11.0 | ^10.13
Requires (Dev)
- xp-framework/test: ^2.0 | ^1.0
- dev-main
- v3.3.0
- v3.2.0
- v3.1.0
- v3.0.0
- v2.15.0
- v2.14.1
- v2.14.0
- v2.13.6
- v2.13.5
- v2.13.4
- v2.13.3
- v2.13.2
- v2.13.1
- v2.13.0
- v2.12.0
- v2.11.0
- v2.10.1
- v2.10.0
- v2.9.1
- v2.9.0
- v2.8.1
- v2.8.0
- v2.7.0
- v2.6.0
- v2.5.0
- v2.4.1
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.0
- v2.0.1
- v2.0.0
- v1.9.1
- v1.9.0
- v1.8.1
- v1.8.0
- v1.7.0
- v1.6.0
- v1.5.0
- v1.4.0
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.1
- v1.0.0
- v0.9.0
- v0.8.0
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- v0.3.1
- v0.3.0
- v0.2.0
- v0.1.1
- v0.1.0
- dev-two
- dev-feature/property-hooks-support
- dev-feature/source
- dev-refactor/always-use-attributes-in-php8
This package is auto-updated.
Last update: 2024-11-02 11:18:24 UTC
README
This library provides a replacement for the XP Framework's reflection API.
Features
Concise: This library aims at reducing code noise of the form if (hasX(...)) { getX() }
by simply returning NULL from its accessor methods. Null handling has improved with the introduction of the null-coalesce operator ??
in PHP 7 and the null-safe invocation operator ?->
in PHP 8 (and in XP Compiler).
PHP 7 & 8: This library handles PHP 8 attributes in both PHP 7 (using the compiler's AST library) and PHP 8 (using its native reflection API).
Subcommand: This library provides an RFC #0303 integration and offers a "reflect" subcommand for the new XP runners. See xp help reflect
on how to use it.
API
The entry point class is the lang.Reflection
class. It can be constructed by passing either objects, type literals (e.g. Date::class
), fully qualified class names (e.g. util.Date
) or lang.XPClass
or PHP's ReflectionClass
instances.
use lang\Reflection; use org\example\{Base, Inject, Fixture}; $type= Reflection::type(Fixture::class); $type->name(); // org.example.Fixture $type->declaredName(); // Fixture $type->literal(); // Fixture::class $type->modifiers(); // Modifiers<public> $type->comment(); // (api doc comment) $type->class(); // lang.XPClass instance $type->classLoader(); // lang.ClassLoader instance $type->package(); // Package or NULL $type->parent(); // Type or NULL $type->interfaces(); // Type[] $type->traits(); // Type[] $type->kind(); // Kind::$INTERFACE, Kind::$TRAIT, Kind::$CLASS, Kind::$ENUM $type->is(Base::class); // true if ($type->instantiable()) { $instance= $type->newInstance('Testing'); } $type->isInstance($instance); // true
Annotations can be accessed by iterating over annotations()
or by the shorthand method annotation()
.
foreach ($type->annotations() as $annotation) { $annotation->type(); // Author::class $annotation->name(); // 'author' $annotation->arguments(); // ['Test', test => true] $annotation->argument(0); // 'Test' $annotation->argument('test'); // true $annotation->newInstance(); // Author class instance } $type->annotation(Inject::class); // Annotation or NULL
The constructor can be accessed via constructor()
. Like members, it provides accessors for modifiers and annotations, as well as its declaring type.
$type->constructor(); // Constructor or NULL if ($constructor= $type->constructor()) { $constructor->name(); // '__construct' $constructor->compoundName(); // 'org.example.Fixture::__construct()' $constructor->modifiers(); // Modifiers<public> $constructor->comment(); // (api doc comment) $constructor->annotations(); // Annotations $constructor->annotation(Inject::class); // Annotation or NULL $constructor->declaredIn(); // Type $constructor->parameters(); // Parameters $constructor->parameter(0); // Parameter or NULL $constructor->newInstance([]); // (instance of the type) }
Type instantiation can be controlled by using initializer()
. It accepts either closures or named references to instance methods.
// Instantiates type without invoking a constructor // Any passed arguments are discarded silently $instance= $type->initializer(null)->newInstance(); // Instantiates type by providing a constructor, regardless of whether one exists or not // Arguments are passed on to the initializer function, which has access to $this $instance= $type->initializer(function($name) { $this->name= $name; })->newInstance(['Test']); // Instantiates type by selecting an instance method as an initializer // The unserialize callback is invoked with ['name' => 'Test'] if ($unserialize= $type->initializer('__unserialize')) { $instance= $unserialize->newInstance([['name' => 'Test']]); }
All members (constants, properties and methods) can be accessed by iterating or by a shorthand lookup by name. Members provide accessors for modifiers and annotations, as well as their declaring type.
$type->constant('POWER'); // Constant or NULL $type->property('value'); // Property or NULL $type->method('fixture'); // Method or NULL foreach ($type->constants() as $name => $constant) { $constant->name(); // 'POWER' $constant->compoundName(); // 'org.example.Fixture::POWER' $constant->value(); // 6100 $constant->modifiers(); // Modifiers<public> $constant->comment(); // (api doc comment) $constant->annotations(); // Annotations $constant->annotation(Inject::class); // Annotation or NULL $constant->declaredIn(); // Type } foreach ($type->properties() as $name => $property) { $property->name(); // 'value' $property->compoundName(); // 'org.example.Fixture::$value' $property->modifiers(); // Modifiers<public> $property->comment(); // (api doc comment) $property->annotations(); // Annotations $property->annotation(Inject::class); // Annotation or NULL $property->declaredIn(); // Type $property->constraint(); // Constraint $property->get($instance); // (property value) $property->set($instance, $value); // (value) } foreach ($type->methods() as $name => $method) { $method->name(); // 'fixture' $method->compoundName(); // 'org.example.Fixture::fixture()' $method->comment(); // (api doc comment) $method->modifiers(); // Modifiers<public> $method->annotations(); // Annotations $method->annotation(Inject::class); // Annotation or NULL $method->declaredIn(); // Type $method->returns(); // Constraint $method->parameters(); // Parameters $method->parameter(0); // Parameter or NULL $method->closure($instance); // Closure instance $method->invoke($instance, []); // (method return value) }
Method and constructor parameters can be retrieved by iterating via parameters()
, by offset parameter($position)
or by name parameter($name)
.
$method->parameter(0); // Parameter or NULL $method->parameter('arg'); // Parameter or NULL $parameters= $method->parameters(); // Parameters instance $parameters->at(0); // Parameter or NULL $parameters->named('arg'); // Parameter or NULL $args= ['test']; if ($parameters->accept($args)) { $method->invoke(null, $args); } foreach ($parameters as $name => $parameter) { $parameter->position(); // 0 $parameter->name(); // 'arg' $parameter->variadic(); // false $parameter->optional(); // true $parameter->default(); // (parameter default value) $parameter->constraint(); // Constraint $parameter->annotations(); // Annotations $parameter->annotation(Inject::class) // Annotation or NULL }
Packages can be reflected upon by passing namespace names to Reflection::of()
.
use lang\Reflection; $package= Reflection::of('org.example'); $package->name(); // org.example $package->literal(); // 'org\example' $package->type('Fixture'); // Type instance $package->types(); // iterable with Type instances $package->parent() // Package or NULL $package->children(); // iterable with Package instances $package->classLoaders(); // iterable with lang.ClassLoader instances