Skip to content
This repository has been archived by the owner on Jan 16, 2019. It is now read-only.

Docs Reflection

Jump to bottom
Frank Kleine edited this page Apr 7, 2012 · 1 revision

Table of Contents

Extended Reflection

Introduction

The Extended Reflection API provided by Stubbles is a layer on top of the default PHP reflection API. For nearly every existing reflection class of PHP an appropriate class exists in Stubbles: 

#php
<?php
class stubReflectionFunction extends ReflectionFunction { }
class stubReflectionParameter extends ReflectionParameter { }
class stubReflectionMethod extends ReflectionMethod { }
class stubReflectionClass extends ReflectionClass { }
class stubReflectionObject extends ReflectionObject { }
class stubReflectionPackage { }
class stubReflectionProperty extends ReflectionProperty { }
class stubReflectionExtension extends ReflectionExtension { }
?>

The only class that has no complement in Stubbles is the ReflectionException class. All classes of the extended reflection API throw this exception in case something goes wrong, you don't need to catch another exception.

On the other hand there is no counterpart for the net::stubbles::reflection::stubReflectionPackage class. Unfortunately PHP5 doesn't have a concept of namespaces until PHP 5.3, therefore it is more like syntactic sugar. We at Stubbles believe that the language would strongly benefit from introducing namespaces and welcome the introduction of namespaces in PHP5.3.

To stay within the extended reflection layer all methods that return another class of the php reflection API have been overloaded to return the appropriate Stubbles reflection class. E.g., if you call the net::stubbles::reflection::stubReflectionClass::getMethod() the result will be an instance of net::stubbles::reflection::stubReflectionMethod. That means if you start reflection with the Stubbles reflection API you will always stay within theses classes, if you start reflection with the default PHP implementation you will stay within the PHP classes.

Any other methods of the default PHP reflection classes remain as they are.

Getting informations about annotations

The extended reflection API offers you something which the default PHP implementation does not have and probably will never have: annotations (see Java annotations for more details how to use this in a programming language). Two additional methods are provided by classes implementing the net::stubbles::reflection::annotations::stubAnnotatable interface: 

#php
<?php
public function hasAnnotation($annotationName);
public function getAnnotation($annotationName);
?>
The first method returns true if the function, method, class or property has an annotation defined with the given name. The second method will return an instance of the annotation (if it does not exist or something goes wrong while creating the instance a ReflectionException is thrown).

The interface is implemented by net::stubbles::reflection::stubReflectionFunction, net::stubbles::reflection::stubReflectionMethod, net::stubbles::reflection::stubReflectionClass, net::stubbles::reflection::stubReflectionObject, net::stubbles::reflection::stubReflectionParameter and net::stubbles::reflection::stubReflectionProperty.

Read more about annotations.

Using the equals() method

Every class has an equals($compare) method which enables to compare the current instance of an reflection class with any other value. The method returns true under the following conditions:

net::stubbles::reflection::stubReflectionClass::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionClass and both reflect the same class
net::stubbles::reflection::stubReflectionExtension::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionExtension and both reflect the same extension
net::stubbles::reflection::stubReflectionFunction::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionFunction and both reflect the same function
net::stubbles::reflection::stubReflectionMethod::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionMethod and both reflect the same method of the same class
net::stubbles::reflection::stubReflectionObject::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionObject and both reflect the same instance of an object (not the same class!)
net::stubbles::reflection::stubReflectionPackage::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionPackage and both reflect the same package
net::stubbles::reflection::stubReflectionParameter::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionParameter and both reflect the same parameter of the same function or of the same method of the same class
net::stubbles::reflection::stubReflectionProperty::equals($compare) if $compare is an instance of net::stubbles::reflection::stubReflectionProperty and both reflect the same property of the same class

Under any other condition the return value is false.

Getting the full qualified class name

The net::stubbles::reflection::stubReflectionClass also provides a new method similar to the built-in getName() to get the fully qualified classname (including package) of a class: 

stubClassLoader::load('net::stubbles::xml::stubDomXMLStreamWriter');
$clazz = new stubReflectionClass('subDomXMLStreamWriter');
print $clazz->getFullQualifiedClassName();

The call to getFullQualifiedClassName() will return net::stubbles::xml::stubDomXMLStreamWriter.

Getting the return type of a method or a function

Both net::stubbles::reflection::stubReflectionMethod and net::stubbles::reflection::stubReflectionFunction offer a method getReturnType() which is capable of returning the return type of a method or function. If the return type is a class the return value is an instance of net::stubbles::reflection::stubReflectionClass, if it is a scalar type or an array the return value is an instance of net::stubbles::reflection::stubReflectionPrimitive and if the method does not have a return value this method returns null.

Please be aware that this is guessing from the doc block with which the method or function is documented. If the doc block is missing or incorrect the return value of this method may be wrong. This is due to missing type hints for return values in PHP itself.

Getting methods or properties of a class by a matcher

Most often you find yourself in situations writing code such as 

$refClass = new stubReflectionClass('MyClass');
foreach ($refClass->getMethods() as $refMethod) {
    if ($refMethod->isPublic() === false) {
        continue;
    }

    if ($refMethod->isStatic() === true) {
        continue;
    }

    // real action here
}

To limit the amount of such if-clauses both classes for reflecting classes, net::stubbles::reflection::stubReflectionClass and net::stubbles::reflection::stubReflectionObject offer the getMethodsByMatcher() and getPropertiesByMatcher() methods. The code from above can be rewritten using a net::stubbles::reflection::matcher::stubMethodMatcher implementation: 

$refClass = new stubReflectionClass('MyClass');
foreach ($refClass->getMethodsByMatcher(new PublicNonStaticMethodMatcher()) as $refMethod) {
    // real action here
}

For properties, the net::stubbles::reflection::matcher::stubPropertyMatcher must be implemented.

Clone this wiki locally