Zend Framework has own Reflection extension. It is mostly build upon genuine PHP Reflection API and extends existing features. The completely new Zend_Reflection module feature is introspection of docBlock tags.

Docblock introspection

Zend_Reflection provides Zend_Reflection_Docblock class, which give us possibility to get some information from docBlock, including: tags (@tag), return type (@return), parameters (@param) and short/long description.

Zend_Reflection_Docblock object can be obtained from class/function/method of file reflectors by getDocblock() method.

$reflectorMethod = new Zend_Reflection_Method('class', 'method');
print get_class($reflectorMethod->getDocblock());
# Zend_Reflection_Docblock

Zend_Reflection_Method is reflection class for methods. Other reflection classes have also Zend_Reflection_ prefix, like Zend_Reflection_File and so on.

Example of docblock usage

/**
* Test class
*/
class Randomizer
{
	/**
	 * Method reponsible for generating random value
	 * 
	 * Some long description
	 * 
	 * @author Slawek
	 * @param int $randMinLimit max limit for rand function
	 * @param int $randMaxLimit max limit for rand function
	 * @return int
	 */
	public function generateRandomValue($randMinLimit, $randMaxLimit)
	{
 
		return rand($randMinLimit, $randMaxLimit);
	}
}
 
$reflectionMethod = new Zend_Reflection_Method('Randomizer', 'generateRandomValue');
$docblock = $reflectionMethod->getDocblock();
 
print $docblock->getShortDescription();
# Method reponsible for generating random value
print $docblock->getLongDescription();
# Some long description
print $docblock->hasTag('author') ? 'YES' : 'NO';
# YES
print $docblock->hasTag('someOtherTag') ? 'YES' : 'NO';
# NO

There are three types of tags: simple tag (Zend_Reflection_Docblock_Tag), return tag (Zend_Reflection_Docblock_Tag_Return) and param tag (Zend_Reflection_Docblock_Tag_Param). Return and Param classes extends Zend_Reflection_Docblock_Tag class.

Docblock class has two methods for retrieving tags – getTag($name) and getTags($filter = null). By default, when we use getTags method – we get all types of tags. But we can use $filter argument – and pass name of interesting tags.

$docblock->getTags()
# array (Zend_Reflection_Docblock_Tag, Zend_Reflection_Docblock_Tag_Param, Zend_Reflection_Docblock_Tag_Param, Zend_Reflection_Docblock_Return)
$docblock->getTags('param')
# array (Zend_Reflection_Docblock_Tag_Param, Zend_Reflection_Docblock_Tag_Param)
$docblock->getTags('author')
# array (Zend_Reflection_Docblock_Tag)

Tags API

$author = $docblock->getTag('author');
print $author->getDescription();
# Slawek
    	
$author = $docblock->getTag('return');
print $author->getType();
# int
    	
$author = $docblock->getTag('param');
foreach ($docblock->getTags('param') as $tag) {
    print sprintf('%s - %s', $tag->getVariableName(), $tag->getType());    		
}
# $randMinLimit - int 
# $randMaxLimit - int

Using docblock class we can provide simple form of annotations to our projects.

Getting method/function content or body

Another neat feature of Zend_Reflection module is possibility to get body/content from method or function. This can be really useful during development process, for instance in our error handling action in development environment.
Getting method body

print $reflectionMethod->getBody();
# return rand($randMinLimit, $randMaxLimit);

Getting method content

print $reflectionMethod->getContents(false); 
# { return rand($randMinLimit, $randMaxLimit); }

with false as first parameter getContents() will not include docblock

More methods can be found at Zend Framework reference guide and inside Zend_Reflection classes code.

No Comments Yet

Leave a Reply →