PHP 5 разполага с цялостен API интерфейс за работа с отражения, което добавя възможността за обратно инженерство (reverse engineering) на класове, интерфейси, функции и методи, както и разширения. Освен това API-интерфейсът за отражения предлага начини за извличане на документиращи коментари за функции, класове и методи.
API-интерфейсът за отражения е обектно-ориентирано разширение на Zend Engine, което се състои от следните класове:
<?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 { }
?>
Забележка: За повече информация относно тези класове, вижте следващите глави.
Нека разгледаме следния пример:
Example #1 Проста употреба на API интерфейса за отражения
<?php
Reflection::export(new ReflectionClass('Exception'));
?>
Примерът по-горе ще изведе:
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 е интерфейс, реализиран от всички класове от тип Reflection, които могат да бъдат експортирани.
<?php
interface Reflector
{
public string __toString()
public static string export()
}
?>
ReflectionException наследява стандартното изключение Exception и се хвърля от API-интерфейса за отражения. Няма специфични методи и свойства.
Класът ReflectionFunction позволява извличане на информация за функции.
<?php
class ReflectionFunction extends ReflectionFunctionAbstract implements Reflector
{
final private __clone()
public void __construct(string name)
public string __toString()
public static string export()
public string getName()
public bool isInternal()
public bool isDisabled()
public mixed getClosure() /* От 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()
}
?>
Родителският клас ReflectionFunctionAbstract има същите методи с изключение на invoke(), invokeArgs(), export() и isDisabled().
Забележка: getNumberOfParameters() и getNumberOfRequiredParameters() бяха добавени в PHP 5.0.3, а invokeArgs() беше добавен в PHP 5.1.0.
За да извършите интроспекция на функция, първо трябва да направите инстанция на класа ReflectionFunction. След това може да извикате който и да е от горните методи на тази инстанция.
Example #2 Употреба на класа ReflectionFunction
<?php
/**
* Обикновен брояч
*
* @return int
*/
function counter()
{
static $c = 0;
return $c++;
}
// Създаване на инстанция на класа ReflectionFunction
$func = new ReflectionFunction('counter');
// Извеждане на основна информация
printf(
"===> %s функция '%s'\n".
" декларирана в %s\n".
" на редове от %d до %d\n",
$func->isInternal() ? 'Вътрешна' : 'Дефинирана от потребителя',
$func->getName(),
$func->getFileName(),
$func->getStartLine(),
$func->getEndline()
);
// Извеждане на документиращ коментар
printf("---> Документация:\n %s\n", var_export($func->getDocComment(), 1));
// Извеждане на статичните променливи, ако има такива
if ($statics = $func->getStaticVariables())
{
printf("---> Статични променливи: %s\n", var_export($statics, 1));
}
// Извикване на функция
printf("---> Резултат от извикването: ");
var_dump($func->invoke());
// може да се използва метода export()
echo "\nReflectionFunction::export() резултат:\n";
echo ReflectionFunction::export('counter');
?>
Забележка: Методът invoke() приема произволен брой аргументи, които се предават към функцията точно както при call_user_func().
Класът ReflectionParameter позволява извличане на информация за параметрите на функции и методи.
<?php
class ReflectionParameter implements Reflector
{
final private __clone()
public void __construct(string function, string parameter)
public string __toString()
public static string export()
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()
}
?>
Забележка: getDefaultValue(), isDefaultValueAvailable() и isOptional() бяха добавени в PHP 5.0.3, a isArray() беше добавен в PHP 5.1.0. getDeclaringFunction() и getPosition() бяха добавени в PHP 5.2.3.
За да извършите интроспекция на параметрите на функция, първо трябва да направите инстанция на класовете ReflectionFunction или ReflectionMethod и да използвате техните методи getParameters(), за да върнете масива от параметри.
Example #3 Употреба на класа ReflectionParameter
<?php
function foo($a, $b, $c) { }
function bar(Exception $a, &$b, $c) { }
function baz(ReflectionFunction $a, $b = 1, $c = null) { }
function abc() { }
// Създаване на инстанция на ReflectionFunction
// с параметри от командния ред
$reflect = new ReflectionFunction($argv[1]);
echo $reflect;
foreach ($reflect->getParameters() as $i => $param) {
printf(
"-- Параметър #%d: %s {\n".
" Клас: %s\n".
" Позволява NULL: %s\n".
" Предаден по адрес: %s\n".
" Опционален?: %s\n".
"}\n",
$i, // $param->getPosition() може да се използва от PHP 5.2.3
$param->getName(),
var_export($param->getClass(), 1),
var_export($param->allowsNull(), 1),
var_export($param->isPassedByReference(), 1),
$param->isOptional() ? 'да' : 'не'
);
}
?>
Класът ReflectionClass позволява извличане на информация за класове и интерфейси.
<?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 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()
}
?>
Забележка: hasConstant(), hasMethod(), hasProperty(), getStaticPropertyValue() и setStaticPropertyValue() бяха добавени в PHP 5.1.0, а newInstanceArgs() беше добавен в PHP 5.1.3.
За да извършите интроспекция на клас, първо трябва да направите инстанция на ReflectionClass. След това може да извикате който и да е от горните методи на тази инстанция.
Example #4 Употреба на класа ReflectionClass
<?php
interface Serializable
{
// ...
}
class Object
{
// ...
}
/**
* Клас Counter
*/
class Counter extends Object implements Serializable
{
const START = 0;
private static $c = Counter::START;
/**
* Извикване на брояча
*
* @access public
* @return int
*/
public function count() {
return self::$c++;
}
}
// Създаване на инстанция на класа ReflectionClass
$class = new ReflectionClass('Counter');
// Извеждане на основна информация
printf(
"===> %s%s%s %s '%s' [наследява %s]\n" .
" деклариран в %s\n" .
" на редове от %d да %d\n" .
" притежава модификатори %d [%s]\n",
$class->isInternal() ? 'Вътрешен' : 'Дефиниран от потребителя',
$class->isAbstract() ? ' абстрактен' : '',
$class->isFinal() ? ' финален' : '',
$class->isInterface() ? ' интерфейс' : ' клас',
$class->getName(),
var_export($class->getParentClass(), 1),
$class->getFileName(),
$class->getStartLine(),
$class->getEndline(),
$class->getModifiers(),
implode(' ', Reflection::getModifierNames($class->getModifiers()))
);
// Извеждане на документиращ коментар
printf("---> Документация:\n %s\n", var_export($class->getDocComment(), 1));
// Извежда интерфейсите реализирани от този клас
printf("---> Реализира:\n %s\n", var_export($class->getInterfaces(), 1));
// Извежда константите на класа
printf("---> Константи: %s\n", var_export($class->getConstants(), 1));
// Извежда свойствата на класа
printf("---> Свойства: %s\n", var_export($class->getProperties(), 1));
// Извежда методите на класа
printf("---> Методи: %s\n", var_export($class->getMethods(), 1));
// Ако класът може да се инстранциира, създава инстранция
if ($class->isInstantiable()) {
$counter = $class->newInstance();
echo '---> $counter е инстанция? ';
echo $class->isInstance($counter) ? 'да' : 'не';
echo "\n---> new Object() е инстанция? ";
echo $class->isInstance(new Object()) ? 'да' : 'не';
}
?>
Забележка: Методът newInstance() приема произволен брой аргументи, които се предават към функцията точно както при call_user_func().
Забележка: $class = new ReflectionClass('Foo'); $class->isInstance($arg) е еквивалентно на $arg instanceof Foo или is_a($arg, 'Foo').
Класът ReflectionObject позволява извършването на обратно инженерство върху обекти.
<?php
class ReflectionObject extends ReflectionClass
{
final private __clone()
public void __construct(mixed object)
public string __toString()
public static string export(mixed object, bool return)
}
?>
Класът ReflectionMethod позволява извличане на информация за методи.
<?php
class ReflectionMethod extends ReflectionFunctionAbstract implements Reflector
{
public void __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 mixed getClosure() /* От PHP 5.3.0 */
public ReflectionClass getDeclaringClass()
// Наследени от 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()
}
?>
За да извършите интроспекция на метод, първо трябва да направите инстанция на ReflectionMethod. След това може да извикате който и да е от горните методи на тази инстанция.
Example #5 Употреба на класа ReflectionMethod
<?php
class Counter
{
private static $c = 0;
/**
* Увеличава брояча
*
* @final
* @static
* @access public
* @return int
*/
final public static function increment()
{
return ++self::$c;
}
}
// Създаване на инстанция на класа ReflectionMethod
$method = new ReflectionMethod('Counter', 'increment');
// Извеждане на основна информация
printf(
"===> %s%s%s%s%s%s%s метод '%s' (който е %s)\n" .
" деклариран в %s\n" .
" на редове от %d до %d\n" .
" притежава модификатори %d[%s]\n",
$method->isInternal() ? 'Вътрешен' : 'Дефиниран от потребителя',
$method->isAbstract() ? ' абстрактен' : '',
$method->isFinal() ? ' финален' : '',
$method->isPublic() ? ' public' : '',
$method->isPrivate() ? ' private' : '',
$method->isProtected() ? ' protected' : '',
$method->isStatic() ? ' статичен' : '',
$method->getName(),
$method->isConstructor() ? 'конструктор' : 'нормален метод',
$method->getFileName(),
$method->getStartLine(),
$method->getEndline(),
$method->getModifiers(),
implode(' ', Reflection::getModifierNames($method->getModifiers()))
);
// Извеждане на документиращ коментар
printf("---> Документация:\n %s\n", var_export($method->getDocComment(), 1));
// Извежда статичните променливи ако съществуват
if ($statics= $method->getStaticVariables()) {
printf("---> Статични променливи: %s\n", var_export($statics, 1));
}
// Извиква метода
printf("---> Резултат от извикването: ");
var_dump($method->invoke(NULL));
?>
Example #6 Getting closure using ReflectionMethod class
<?php
class Example {
static function printer () {
echo "Hello World!\n";
}
}
$class = new ReflectionClass('Example');
$method = $class->getMethod('printer');
$closure = $method->getClosure(); /* От PHP 5.3.0 */
$closure(); // Hello World!
?>
Забележка: Опитът да се извика private, protected или абстрактен метод ще доведе до генериране на изключение от метода invoke().
Забележка: Както се вижда от примера по-горе, при статични методи, трябва да се предава NULL като първи аргумент на invoke(). При нестатични методи, се предава инстанцията на класа.
Класът ReflectionProperty позволява извличане на информация за свойства.
<?php
class ReflectionProperty implements Reflector
{
final private __clone()
public void __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() /* От 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()
}
?>
Забележка: getDocComment() беше добавен в PHP 5.1.0. setAccessible() беше добавен в PHP 5.3.0.
За да извършите интроспекция на свойство, първо трябва да направите инстанция на ReflectionProperty. След това може да извикате който и да е от горните методи на тази инстанция.
Example #7 Употреба на класа ReflectionProperty
<?php
class String
{
public $length = 5;
}
// Създаване на инстанция на класа ReflectionProperty
$prop = new ReflectionProperty('String', 'length');
// Извеждане на основна информация
printf(
"===> %s%s%s%s свойството '%s' (което беше %s)\n" .
" притежава модификатори %s\n",
$prop->isPublic() ? ' public' : '',
$prop->isPrivate() ? ' private' : '',
$prop->isProtected() ? ' protected' : '',
$prop->isStatic() ? ' статичен' : '',
$prop->getName(),
$prop->isDefault() ? 'декларирано по време на компилация' : 'създадено по време на стартиране',
var_export(Reflection::getModifierNames($prop->getModifiers()), 1)
);
// Създаване на инстанция на String
$obj= new String();
// Връщане на текущата стойност
printf("---> Стойността е: ");
var_dump($prop->getValue($obj));
// Променяне на стойността
$prop->setValue($obj, 10);
printf("---> Установяване а стойността в 10, новата стойност е: ");
var_dump($prop->getValue($obj));
// Dump на обекта
var_dump($obj);
?>
Example #8 Връщане на стойност от private и protected свойство посредством класа ReflectionProperty
<?php
class Foo {
public $x = 1;
protected $y = 2;
private $z = 3;
}
$obj = new Foo;
$prop = new ReflectionProperty('Foo', 'y');
$prop->setAccessible(true); /* От PHP 5.3.0 */
var_dump($prop->getValue($obj)); // int(2)
$prop = new ReflectionProperty('Foo', 'z');
$prop->setAccessible(true); /* От PHP 5.3.0 */
var_dump($prop->getValue($obj)); // int(2)
?>
Забележка: Опитът да се вземе или установи стойнстта на private или protected свойсво на клас ще предизвика генериране на изключение.
Класът ReflectionExtension позволява извличане на информация за разширения. Можете да извлечете всички заредени разширения по време на изпълнение чрез get_loaded_extensions().
<?php
class ReflectionExtension 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 string getVersion()
public ReflectionFunction[] getFunctions()
public array getConstants()
public array getINIEntries()
public ReflectionClass[] getClasses()
public array getClassNames()
public string info()
}
?>
За да извършите интроспекция на разширение, първо трябва да направите инстанция на ReflectionExtension. След това може да извикате който и да е от горните методи на тази инстанция.
Example #9 Употреба на класа ReflectionExtension
<?php
// Създаване на инстанция на класа ReflectionExtension
$ext = new ReflectionExtension('standard');
// Извеждане на основна информация
printf(
"Наименование : %s\n" .
"Версия : %s\n" .
"Функции : [%d] %s\n" .
"Константи : [%d] %s\n" .
"INI стойности : [%d] %s\n" .
"Класове : [%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)
);
?>
В случай че искате да създадете специализирани версии на вградените класове (примерно за да оцветите кода HTML при експортиране посредством лесни за достъп свойства вместо чрез методи или чрез прилагането на методи от тип utility), можете спокойно да ги наследите.
Example #10 Наследяване на вградени класове
<?php
/**
* Клас My_Reflection_Method
*/
class My_Reflection_Method extends ReflectionMethod
{
public $visibility = array();
public function __construct($o, $m)
{
parent::__construct($o, $m);
$this->visibility= Reflection::getModifierNames($this->getModifiers());
}
}
/**
* Демонстрационен клас #1
*
*/
class T {
protected function x() {}
}
/**
* Демонстрационен клас #2
*
*/
class U extends T {
function x() {}
}
// Извеждане на информацията
var_dump(new My_Reflection_Method('U', 'x'));
?>
Забележка: Внимание: Ако предефинирате конструктор, не забравяйте да извикате конструктора на родителския клас преди всякакъв друг код. В противен случай резултатът ще е следния: Fatal error: Internal error: Failed to retrieve the reflection object