Reflection/design/design.txt

eZ component: Reflection, Design
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Reflection API of PHP
(http://www.php.net/manual/en/language.oop5.reflection.php) itself is
implemented as an extension written in C for maximum performance and conceptual
reasons. The Reflection component is based on this PHP extension and several
elements are derived from the given base classes.

Design description
------------------

The Reflection component is shown in the class diagram. For
all classes of the Reflection API new subclasses are introduced which provide
additional functionality and methods to access annotations and data types.

ezcReflectionClass
	ezcReflectionClass inherits from ReflectionClass and redefines all methods
	which return a PHP reflection object to return objects from the Reflection
	component. In addition to that methods for annotation handling are
	introduced e.g. getTags getAnnotations, isTagged hasAnnotation. The generic
	getDocComment method is superseded by getShortDescription and
	getLongDescription. These methods return only the relevant parts of interest
	from a PHPDoc comment.

	class ezcReflectionClass extends ReflectionClass {
	    public void __construct(string $name)
	    public ezcReflectionMethod getMethod(string $name)
	    public ezcReflectionMethod getConstructor()
	    public ezcReflectionMethod[] getMethods()
	    public ezcReflectionClassType getParentClass()
	    public ezcReflectionProperty getProperty(string $name)
	    public ezcReflectionProperty[] getProperties()
	    public boolean isWebService()
	    public string getShortDescription()
	    public string getLongDescription()
	    public boolean isTagged(string $with)
	    public ezcReflectionDocTag[] getTags(string $name)
	    public ezcReflectionExtension getExtension()
	}

The enhancements to the Reflection API in the classes ezcReflectionFunction,
ezcReflectionMethod, ezcReflectionParameter, ezcReflectionProperty and
ezcReflectionExtension are analogue to those made in ezcReflectionClass and have
a similar behavior.

	class ezcReflectionExtension extends ReflectionExtension {
	    public void __construct(string $name)
	    public ezcReflectionFunction[] getFunctions()
	    public ezcReflectionClass[] getClasses()
	}
	
	class ezcReflectionFunction extends ReflectionFunction {
	    public void __construct(string $name)
	    public ezcReflectionParameter[] getParameters()
	    public ezcReflectionType getReturnType()
	    public string getReturnDescription()
	    public boolean isWebmethod()
	    public string getShortDescription()
	    public string getLongDescription()
	    public boolean isTagged(string $with)
	    public ezcReflectionDocTag[] getTags(string $name)
	}
	
	class ezcReflectionMethod extends ReflectionMethod {
	    public void __construct(mixed class, string name)
	    public ezcReflectionParameter[] getParameters()
	    public ezcReflectionType getReturnType()
	    public string getReturnDescription()
	    public boolean isWebmethod()
	    public string getShortDescription()
	    public string getLongDescription()
	    public boolean isTagged(string $with)
	    public ezcReflectionDocTag[] getTags(string $name)
	    public boolean isMagic()
	    public ezcReflectionClassType getDeclaringClass()
	}
	
	class ezcReflectionParameter extends ReflectionParameter {
	    public void __construct(mixed mixed, mixed parameter)
	    public ezcReflectionType getType()
	    public ezcReflectionClassType getClass()
	    public ezcReflectionFunction getDeclaringFunction()
	    public ezcReflectionClassType getDeclaringClass()
	}
	
	class ezcReflectionProperty extends ReflectionProperty {
	    public void __construct(mixed class, string name)
	    public ezcReflectionType getType()
	    public ezcReflectionClassType getDeclaringClass()
	}


ezcReflection
	A static class called ezcReflection is defined which acts as a central
	entry point and factory for reflection.
	It holds a factory for reflection type objects and a factory for
	documentation parser objects.
	
	getTypeByName will return the appropriate type object for a given data type
	name e.g., specified in an annotation.
	For extensibility it is possible to set a different factory for type objects
	and implement custom type objects with new features.
	
	Currently the ezcReflectionPhpDocParser is used to parse the documentation
	to gather type information. If another documentation style then PHPDoc is used
	a new parser can be set with setDocParser. The parser object has to support
	the clone operation, because each new type object got its own parser object.

ezcReflectionTypeFactory
	A type factory has to implement the interface ezcReflectionTypeFactory and
	can be used to extend the provided type system with additional features.

ezcReflectionTypeFactoryImpl
	If no type factory is provided the default implementation
	ezcReflectionTypeFactoryImpl is chosen which performs proper data type
	mapping for type names provided as strings.

	class ezcReflection {
	    public static ezcReflectionDocParser getDocParserInstance()
	    public static setDocParser(ezcReflectionDocParser $docParser)
	    public void setReflectionTypeFactory(ezcReflectionTypeFactory $factory)
	    public static ezcReflectionType getTypeByName(string $typeName)
   	}

ezcReflectionTypeMapper
	ezcReflectionTypeMapper is a helper class used by the default type factory,
	the primitive type class and some of the annotation classes. It provides
	mappings from various type names which may occur in documentation to
	standardized type names or XML Schema data types.

ezcReflectionType
	The type interface acts as a central interface for the type system. It is
	equipped with several methods to reflect characteristics of a data type. For
	convenience and usability also methods for an XML Schema mapping are
	incorporated at this point.

	interface ezcReflectionType {
	    function ezcReflectionType getArrayType();
	    function ezcReflectionType getMapIndexType();
	    function ezcReflectionType getMapValueType();
	    function boolean isArray();
	    function boolean isClass();
	    function boolean isPrimitive();
	    function boolean isMap();
	    function string toString();
	    function boolean isStandardType();
	    function string getXmlName();
	    function DOMElement getXmlSchema(DOMDocument $dom);
	}

ezcReflectionAbstractType
	The abstract type is one implementation of the type interface and serves as
	an abstract base class for ezcReflectionPrimitiveType and
	ezcReflectionArrayType.

ezcReflectionPrimitiveType
	The primitive type is a specialization of ezcReflectionAbstractType and
	represents the primitive types boolean, integer, float, string and resource.

ezcReflectionArrayType
	The array type is the second class to extend ezcReflectionAbstractType and
	it distinguishes between simple arrays and maps.

ezcReflectionClassType
	This implementation of the type interface represents a class as a type. For
	this purpose it is a specialization of ezcReflectionClass to inherit all its
	capabilities, i.e. unlike ezcReflectionPrimitiveType and
	ezcReflectionArrayType the ezcReflectionClassType is tightly integrated with
	the Reflection API.

	class ezcReflectionClassType extends ezcReflectionClass implements ezcReflectionType {
	    public ezcReflectionType getArrayType()
	    public ezcReflectionType getMapIndexType()
	    public ezcReflectionType getMapValueType()
	    public boolean isArray()
	    public boolean isClass()
	    public boolean isPrimitive()
	    public boolean isMap()
	    public string toString()
	    public boolean isStandardType()
	    public string getXmlName(boolean $usePrefix)
	    public DOMElement getXmlSchema(DOMDocument dom, namespaceXSD)
	    public void __construct(string $name)
	}

ezcReflectionDocParser
	Is an generic documentation parser interface to be able to parse what ever
	documentation style is used. 

ezcReflectionPhpDocParser
	This class parses PHPDoc comments and provides retrieved data in the form
	of annotation objects.

ezcReflectionAnnotationFactory
	This factory creates an ezcReflectionAnnotation object for a given
	annotation.

ezcReflectionAnnotation
	This is a generic class to represent an annotation and it also serves as a
	base class for several specialized annotation classes, e.g.
	ezcReflectionAnnotationParam, ezcReflectionAnnotationReturn and
	ezcReflectionAnnotationVar.

ezcReflectionAnnotationWebService
    This annotation declares a class as to be published as a SOAP or ReST Web Service

ezcReflectionAnnotationWebMethod
    This annotation declares a method as to be published as a WSDL Operation of a SOAP Web Service

ezcReflectionAnnotationRestMethod
    This annotation declares a method as to be published as a ReSTful Web Service;
    The first parameter specifies the HTTP verb and the second one is a regular
    expression for retrieving the method's arguments from a request URI.

ezcReflectionAnnotationRestIn
    This annotation specifies the deserializer class for a ReSTful Web Service.

ezcReflectionAnnotationRestOut
    This annotation specifies serializer class for a ReSTful Web Service.

Guidelines
----------

Algorithms
----------

Data structures
---------------

Diagrams
========

class_diagram.png - Class diagram of the Reflection component and its type system
php-reflection-api.png - Class diagram of the PHP5 Reflection API