PHP 5 bringt eine komplette Reflection-API mit, die Möglichkeiten bietet, um Klassen, Interfaces, Funktionen und Methoden ebenso wie auch Extensions zurückzuentwickeln. Zusätzlich bietet die Reflection-API Wege, dokumentarische Kommentare von Funktionen, Klassen und Methoden abzufragen.
Die Reflection-API ist eine objektorientierte Erweiterung der Zend Engine, bestehend aus den folgenden Klassen:
<?php
class Reflection { }
interface Reflector { }
class ReflectionException extends Exception { }
class ReflectionFunction extends ReflectionFunctionAbstract implements Reflector { }
class ReflectionParameter implements Reflector { }
class ReflectionMethod extends ReflectionFunctionAbstract implements Reflector { }
class ReflectionClass implements Reflector { }
class ReflectionObject extends ReflectionClass { }
class ReflectionProperty implements Reflector { }
class ReflectionExtension implements Reflector { }
?>
Hinweis: Für detailierte Erläuterungen dieser Klassen werfen Sie einen Blick auf die nächsten Kapitel.
Wenn wir den unten stehenden Beispielcode ausführen würden:
Beispiel #1 Grundlegende Nutzung der Reflection-API
<?php
Reflection::export(new ReflectionClass('Exception'));
?>
Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
Class [ <internal> class Exception ] {
- Constants [0] {
}
- Static properties [0] {
}
- Static methods [0] {
}
- Properties [6] {
Property [ <default> protected $message ]
Property [ <default> private $string ]
Property [ <default> protected $code ]
Property [ <default> protected $file ]
Property [ <default> protected $line ]
Property [ <default> private $trace ]
}
- Methods [9] {
Method [ <internal> final private method __clone ] {
}
Method [ <internal, ctor> public method __construct ] {
- Parameters [2] {
Parameter #0 [ <optional> $message ]
Parameter #1 [ <optional> $code ]
}
}
Method [ <internal> final public method getMessage ] {
}
Method [ <internal> final public method getCode ] {
}
Method [ <internal> final public method getFile ] {
}
Method [ <internal> final public method getLine ] {
}
Method [ <internal> final public method getTrace ] {
}
Method [ <internal> final public method getTraceAsString ] {
}
Method [ <internal> public method __toString ] {
}
}
}
Reflector ist ein von allen Reflektionsklassen implementiertes Interface.
<?php
interface Reflector
{
public string __toString()
public static string export()
}
?>
ReflectionException erweitert die normale Exception und wird von der Reflection-API geworfen. Es werden keine spezifischen Methoden oder Eigenschaften eingeführt.
Die ReflectionFunction-Klasse lässt Sie Funktionen zurückentwickeln.
<?php
class ReflectionFunction extends ReflectionFunctionAbstract implements Reflector
{
final private __clone()
public void __construct(string name)
public string __toString()
public static string export(string name, bool return)
public string getName()
public bool isInternal()
public bool isDisabled()
public mixed getClosure() /* Ab PHP 5.3.0 */
public bool isUserDefined()
public string getFileName()
public int getStartLine()
public int getEndLine()
public string getDocComment()
public array getStaticVariables()
public mixed invoke([mixed args [, ...]])
public mixed invokeArgs(array args)
public bool returnsReference()
public ReflectionParameter[] getParameters()
public int getNumberOfParameters()
public int getNumberOfRequiredParameters()
}
?>
Die Elternklasse ReflectionFunctionAbstract hat die gleichen Methoden mit Ausnahme von invoke(), invokeArgs(), export() und isDisabled().
Hinweis: getNumberOfParameters() und getNumberOfRequiredParameters() wurden in PHP 5.0.3 hinzugefügt, während invokeArgs() in PHP 5.1.0 neu hinzukam.
Um einen Blick in eine Funktion zu werfen, muss man erst eine Instanz der Klasse ReflectionFunction erzeugen. Danach kann man jede der oben aufgeführten Methoden dieser Instanz aufrufen.
Beispiel #2 Die ReflectionFunction-Klasse benutzen
<?php
/**
* Ein einfacher Zähler
*
* @return int
*/
function counter()
{
static $c = 0;
return $c++;
}
// Erzeuge eine neue Instanz der ReflectionFunction-Klasse
$func = new ReflectionFunction('counter');
// Grundlegende Informationen ausgeben
printf(
"===> Die %s Funktion '%s'\n".
" ist deklariert in %s\n".
" Zeilen %d bis %d\n",
$func->isInternal() ? 'interne' : 'benutzerdefinierte',
$func->getName(),
$func->getFileName(),
$func->getStartLine(),
$func->getEndline()
);
// Dokumentarischen Kommentar ausgeben
printf("---> Dokumentation:\n %s\n", var_export($func->getDocComment(), 1));
// Statische Variablen ausgeben, wenn welche existieren
if ($statics = $func->getStaticVariables())
{
printf("---> Statische Variablen: %s\n", var_export($statics, 1));
}
// Die Funktion aufrufen
printf("---> Der Aufruf gibt zurück: ");
var_dump($func->invoke());
// Sie könnten bevorzugen, die export()-Methode zu verwenden
echo "\nReflectionFunction::export() gibt zurück:\n";
echo ReflectionFunction::export('counter');
?>
Hinweis: Die Methode invoke() akzeptiert eine variable Anzahl von Argumenten, welche genau wie von call_user_func() an die Funktion übergeben werden.
Die ReflectionParameter-Klasse fragt Informationen über die Parameter einer Funktion oder Methode ab.
<?php
class ReflectionParameter implements Reflector
{
final private __clone()
public void __construct(string function, string parameter)
public string __toString()
public static string export(mixed function, mixed parameter, bool return)
public string getName()
public bool isPassedByReference()
public ReflectionClass getDeclaringClass()
public ReflectionClass getClass()
public bool isArray()
public bool allowsNull()
public bool isPassedByReference()
public bool isOptional()
public bool isDefaultValueAvailable()
public mixed getDefaultValue()
public int getPosition()
}
?>
Hinweis: getDefaultValue(), isDefaultValueAvailable() und isOptional() wurden in PHP 5.0.3 hinzugefügt, während isArray() in PHP 5.1.0 neu ist. getDeclaringFunction() und getPosition() wurden in PHP 5.1.3 hinzugefügt.
Um einen Blick in Funktionsparameter zu werfen, muss man zuerst eine Instanz der Klassen ReflectionFunction oder ReflectionMethod erzeugen und kann dann deren getParameters() Methode verwenden, um ein Array ihrer Parameter abzufragen.
Beispiel #3 Die ReflectionParameter-Klasse verwenden
<?php
function foo($a, $b, $c) { }
function bar(Exception $a, &$b, $c) { }
function baz(ReflectionFunction $a, $b = 1, $c = null) { }
function abc() { }
// Erzeuge eine Instanz von ReflectionFunction mit dem
// auf der Kommandozeile übergebenen Parameter
$reflect = new ReflectionFunction($argv[1]);
echo $reflect;
foreach ($reflect->getParameters() as $i => $param) {
printf(
"-- Parameter #%d: %s {\n".
" Klasse: %s\n".
" Erlaubt NULL: %s\n".
" Als Referenz übergeben: %s\n".
" Ist optional?: %s\n".
"}\n",
$i, // ab PHP 5.2.3 kann auch $param->getPosition() genutzt werden
$param->getName(),
var_export($param->getClass(), 1),
var_export($param->allowsNull(), 1),
var_export($param->isPassedByReference(), 1),
$param->isOptional() ? 'ja' : 'nein'
);
}
?>
Die ReflectionClass-Klasse erlaubt es, Klassen und Interfaces zurückzuentwickeln.
<?php
class ReflectionClass implements Reflector
{
final private __clone()
public void __construct(string name)
public string __toString()
public static string export(mixed class, bool return)
public string getName()
public bool isInternal()
public bool isUserDefined()
public bool isInstantiable()
public bool hasConstant(string name)
public bool hasMethod(string name)
public bool hasProperty(string name)
public string getFileName()
public int getStartLine()
public int getEndLine()
public string getDocComment()
public ReflectionMethod getConstructor()
public ReflectionMethod getMethod(string name)
public ReflectionMethod[] getMethods()
public ReflectionProperty getProperty(string name)
public ReflectionProperty[] getProperties()
public array getConstants()
public mixed getConstant(string name)
public ReflectionClass[] getInterfaces()
public bool isInterface()
public bool isAbstract()
public bool isFinal()
public int getModifiers()
public mixed getClosure() /* Ab PHP 5.3.0 */
public bool isInstance(stdclass object)
public stdclass newInstance(mixed args)
public stdclass newInstanceArgs(array args)
public ReflectionClass getParentClass()
public bool isSubclassOf(ReflectionClass class)
public array getStaticProperties()
public mixed getStaticPropertyValue(string name [, mixed default])
public void setStaticPropertyValue(string name, mixed value)
public array getDefaultProperties()
public bool isIterateable()
public bool implementsInterface(string name)
public ReflectionExtension getExtension()
public string getExtensionName()
}
?>
Hinweis: hasConstant(), hasMethod(), hasProperty(), getStaticPropertyValue() und setStaticPropertyValue() wurden in PHP 5.1.0 hinzugefügt, während newInstanceArgs() in PHP 5.1.3 dazu kam.
Um einen Blick in eine Klasse zu werfen, muss man zuerst eine Instanz der Klasse ReflectionClass erzeugen. Man kann danach jede der oben angeführten Methoden der Instanz verwenden.
Beispiel #4 Die ReflectionClass-Klasse verwenden
<?php
interface Serializable
{
// ...
}
class Object
{
// ...
}
/**
* Eine Zählerklasse
*/
class Counter extends Object implements Serializable
{
const START = 0;
private static $c = Counter::START;
/**
* Zähler aufrufen
*
* @access public
* @return int
*/
public function count() {
return self::$c++;
}
}
// Eine Instanz der Klasse ReflectionClass erzeugen
$class = new ReflectionClass('Counter');
// Grundlegende Informationen ausgeben
printf(
"===> %s%s%s %s '%s' [extends %s]\n" .
" deklariert in %s\n" .
" Zeilen %d bis %d\n" .
" hat die Modifizierer %d [%s]\n",
$class->isInternal() ? 'internal' : 'user-defined',
$class->isAbstract() ? ' abstract' : '',
$class->isFinal() ? ' final' : '',
$class->isInterface() ? 'interface' : 'class',
$class->getName(),
var_export($class->getParentClass(), 1),
$class->getFileName(),
$class->getStartLine(),
$class->getEndline(),
$class->getModifiers(),
implode(' ', Reflection::getModifierNames($class->getModifiers()))
);
// Dokumentarischen Kommentar ausgeben
printf("---> Dokumentation:\n %s\n", var_export($class->getDocComment(), 1));
// Ausgeben, welche Interfaces von der Klasse implementiert werden
printf("---> Implementiert:\n %s\n", var_export($class->getInterfaces(), 1));
// Klassenkonstanten ausgeben
printf("---> Konstanten: %s\n", var_export($class->getConstants(), 1));
// Klasseneigenschaften ausgeben
printf("---> Eigenschaften: %s\n", var_export($class->getProperties(), 1));
// Klassenmethoden ausgeben
printf("---> Methoden: %s\n", var_export($class->getMethods(), 1));
// Wenn die Klassen instantiierbar ist, erzeuge eine Instanz
if ($class->isInstantiable()) {
$counter = $class->newInstance();
echo '---> Ist $counter Instanz? ';
echo $class->isInstance($counter) ? 'ja' : 'nein';
echo "\n---> ist new Object() Instanz? ";
echo $class->isInstance(new Object()) ? 'ja' : 'nein';
}
?>
Hinweis: Die Methode newInstance() akzeptiert eine variable Anzahl von Argumenten, welche der Funktion genau wie in call_user_func() übergeben werden.
Hinweis: $class = new ReflectionClass('Foo'); $class->isInstance($arg) ist äquivalent zu $arg instanceof Foo oder is_a($arg, 'Foo').
Die Klasse ReflectionObject erlaubt das Zurückentwickeln von Objekten.
<?php
class ReflectionObject extends ReflectionClass
{
final private __clone()
public void __construct(mixed object)
public string __toString()
public static string export(mixed object, bool return)
}
?>
Die ReflectionMethod-Klasse erlaubt es, Klassenmethoden zurückzuentwickeln.
<?php
class ReflectionMethod extends ReflectionFunctionAbstract implements Reflector
{
public __construct(mixed class, string name)
public string __toString()
public static string export(mixed class, string name, bool return)
public mixed invoke(stdclass object [, mixed args [, ...]])
public mixed invokeArgs(stdclass object, array args)
public bool isFinal()
public bool isAbstract()
public bool isPublic()
public bool isPrivate()
public bool isProtected()
public bool isStatic()
public bool isConstructor()
public bool isDestructor()
public int getModifiers()
public ReflectionClass getDeclaringClass()
// Ererbt von ReflectionFunctionAbstract
final private __clone()
public string getName()
public bool isInternal()
public bool isUserDefined()
public string getFileName()
public int getStartLine()
public int getEndLine()
public string getDocComment()
public array getStaticVariables()
public bool returnsReference()
public ReflectionParameter[] getParameters()
public int getNumberOfParameters()
public int getNumberOfRequiredParameters()
}
?>
Um einen Blick in eine Methode zu werfen, muss man zuerst eine Instanz der ReflectionMethod Klasse erzeugen. Man kann dann jede der oben aufgeführten Methoden dieser Instanz aufrufen.
Beispiel #5 Die ReflectionMethod-Klasse verwenden
<?php
class Counter
{
private static $c = 0;
/**
* Zähler erhöhen
*
* @final
* @static
* @access public
* @return int
*/
final public static function increment()
{
return ++self::$c;
}
}
// Erzeuge eine Instanz der ReflectionMethod-Klasse
$method = new ReflectionMethod('Counter', 'increment');
// Grundlegende Informationen ausgeben
printf(
"===> Die %s%s%s%s%s%s%s Methode '%s' (welche %s ist)\n" .
" deklariert in %s\n" .
" Zeilen %d bis %d\n" .
" hat die Modifizierer %d[%s]\n",
$method->isInternal() ? 'interne' : 'benutzerdefinierte',
$method->isAbstract() ? ' abstract' : '',
$method->isFinal() ? ' final' : '',
$method->isPublic() ? ' public' : '',
$method->isPrivate() ? ' private' : '',
$method->isProtected() ? ' protected' : '',
$method->isStatic() ? ' static' : '',
$method->getName(),
$method->isConstructor() ? 'der Konstruktor' : 'eine normale Methode',
$method->getFileName(),
$method->getStartLine(),
$method->getEndline(),
$method->getModifiers(),
implode(' ', Reflection::getModifierNames($method->getModifiers()))
);
// Dokumentarischen Kommentar ausgeben
printf("---> Dokumentation:\n %s\n", var_export($method->getDocComment(), 1));
// Statische Variablen ausgeben, falls welche existieren
if ($statics= $method->getStaticVariables()) {
printf("---> Statische Variablen: %s\n", var_export($statics, 1));
}
// Die Methode aufrufen
printf("---> Aufruf gibt zurück: ");
var_dump($method->invoke(NULL));
?>
Beispiel #6 Closure mit Hilfe der ReflectionMethod-Klasse abfragen
<?php
class Example {
static function printer () {
echo "Hello World!\n";
}
}
$class = new ReflectionClass('Example');
$method = $class->getMethod('printer');
$closure = $method->getClosure(); /* Ab PHP 5.3.0 */
$closure(); // Hello World!
?>
Hinweis: Der Versuch, eine private-, protected- oder abstract-Methode aufzurufen, wird darin enden, dass eine Exception aus der invoke()-Methode geworfen wird.
Hinweis: Für statische Methoden sollten Sie, wie man oben sieht, NULL als erstes Argument von invoke() übergeben. Für nicht-statische Methoden übergeben Sie eine Instanz der Klasse.
Die ReflectionProperty-Klasse lässt Sie Klasseneigenschaften zurückentwickeln.
<?php
class ReflectionProperty implements Reflector
{
final private __clone()
public __construct(mixed class, string name)
public string __toString()
public static string export(mixed class, string name, bool return)
public string getName()
public bool isPublic()
public bool isPrivate()
public bool isProtected()
public bool isStatic()
public bool isDefault()
public void setAccessible() /* Ab PHP 5.3.0 */
public int getModifiers()
public mixed getValue(stdclass object)
public void setValue(stdclass object, mixed value)
public ReflectionClass getDeclaringClass()
public string getDocComment()
}
?>
Hinweis: getDocComment() wurde in PHP 5.1.0 hinzugefügt. setAccessible() wurde in PHP 5.3.0 hinzugefügt.
Um einen Blick in eine Eigenschaft zu werfen, müssen Sie zuerst eine Instanz der Klasse ReflectionProperty erzeugen. Danach können Sie jede der oben angeführten Methoden der Instanz aufrufen.
Beispiel #7 Die ReflectionProperty-Klasse verwenden
<?php
class String
{
public $laenge = 5;
}
// Erzeuge eine Instanz der Klasse ReflectionPropety
$prop = new ReflectionProperty('String', 'laenge');
// Grundlegende Informationen ausgeben
printf(
"===> Die %s%s%s%s Eigenschaft '%s' (welche %s wurde)\n" .
" hat die Modizifierer %s\n",
$prop->isPublic() ? ' public' : '',
$prop->isPrivate() ? ' private' : '',
$prop->isProtected() ? ' protected' : '',
$prop->isStatic() ? ' static' : '',
$prop->getName(),
$prop->isDefault() ? 'zur Kompilierungszeit deklariert' :
'zur Laufzeit erzeugt',
var_export(Reflection::getModifierNames($prop->getModifiers()), 1)
);
// Eine Instanz von String erzeugen
$obj= new String();
// Aktuellen Wert abfragen
printf("---> Wert ist: ");
var_dump($prop->getValue($obj));
// Wert ändern
$prop->setValue($obj, 10);
printf("---> Setze Wert auf 10, neuer Wert ist: ");
var_dump($prop->getValue($obj));
// Objekt ausgeben
var_dump($obj);
?>
Beispiel #8 Werte von private- und protected-Klasseneigenschaften mit der ReflectionProperty-Klasse bestimmen
<?php
class Foo {
public $x = 1;
protected $y = 2;
private $z = 3;
}
$obj = new Foo;
$prop = new ReflectionProperty('Foo', 'y');
$prop->setAccessible(true); /* As of PHP 5.3.0 */
var_dump($prop->getValue($obj)); // int(2)
$prop = new ReflectionProperty('Foo', 'z');
$prop->setAccessible(true); /* As of PHP 5.3.0 */
var_dump($prop->getValue($obj)); // int(2)
?>
Hinweis: Der Versuch, den Wert einer private- oder protected-Klasseneigenschaft zu lesen oder zu setzen, wird darin enden, dass eine Exception geworfen wird.
Die ReflectionExtension-Klasse lässt Sie Extensions zurückentwickeln. Man kann alle geladenen Extensions zur Laufzeit mittels get_loaded_extensions() abrufen.
<?php
class ReflectionExtension implements Reflector {
final private __clone()
public __construct(string name)
public string __toString()
public static string export(string name, bool return)
public string getName()
public string getVersion()
public ReflectionFunction[] getFunctions()
public array getConstants()
public array getINIEntries()
public ReflectionClass[] getClasses()
public array getClassNames()
public string info()
}
?>
Um einen Blick in eine Extension zu werfen, muss man zuerst eine Instanz der Klasse ReflectionExtension erzeugen. Danach kann man alle oben aufgeführten Methoden der Instanz aufrufen.
Beispiel #9 Die ReflectionExtension-Klasse verwenden
<?php
// Erzeuge eine neue Instanz der ReflectionExtension-Klasse
$ext = new ReflectionExtension('standard');
// Grundlegende Informationen ausgeben
printf(
"Name : %s\n" .
"Version : %s\n" .
"Funktionen : [%d] %s\n" .
"Konstanten : [%d] %s\n" .
"INI Einträge : [%d] %s\n" .
"Klassen : [%d] %s\n",
$ext->getName(),
$ext->getVersion() ? $ext->getVersion() : 'NO_VERSION',
sizeof($ext->getFunctions()),
var_export($ext->getFunctions(), 1),
sizeof($ext->getConstants()),
var_export($ext->getConstants(), 1),
sizeof($ext->getINIEntries()),
var_export($ext->getINIEntries(), 1),
sizeof($ext->getClassNames()),
var_export($ext->getClassNames(), 1)
);
?>
Für den Fall, dass Sie spezialisierte Versionen der eingebauten Klassen erzeugen wollen (zum Beispiel, um kolorierte HTML-Ausgaben zu erzeugen oder leicht zugängliche Klassenvariablen oder -methoden oder Hilfsmethoden hinzuzufügen), können Sie fortfahren und die Klassen ableiten.
Beispiel #10 Erweiterung der eingebauten Klassen
<?php
/**
* Meine Reflection_Method-Klasse
*/
class My_Reflection_Method extends ReflectionMethod
{
public $visibility = array();
public function __construct($o, $m)
{
parent::__construct($o, $m);
$this->visibility= Reflection::getModifierNames($this->getModifiers());
}
}
/**
* Demoklasse #1
*
*/
class T {
protected function x() {}
}
/**
* Demoklasse #2
*
*/
class U extends T {
function x() {}
}
// Informationen ausgeben
var_dump(new My_Reflection_Method('U', 'x'));
?>
Hinweis: Achtung: Wenn Sie den Konstruktor überschreiben, denken Sie daran, den Vaterkonstruktor _vor_ jedem anderen Code, den Sie hinzufügen, aufzurufen. Unterlassung wird zu folgendem Ergebnis führen: Fatal error: Internal error: Failed to retrieve the reflection object