Subversion-Projekte lars-tiefland.prado

<?php
/**
 * TComponent, TPropertyValue classes
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.pradosoft.com/
 * @copyright Copyright &copy; 2005-2008 PradoSoft
 * @license http://www.pradosoft.com/license/
 * @version $Id: TComponent.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @package System
 */

/**
 * TComponent class
 *
 * TComponent is the base class for all PRADO components.
 * TComponent implements the protocol of defining, using properties and events.
 *
 * A property is defined by a getter method, and/or a setter method.
 * Properties can be accessed in the way like accessing normal object members.
 * Reading or writing a property will cause the invocation of the corresponding
 * getter or setter method, e.g.,
 * <code>
 * $a=$this->Text;     // equivalent to $a=$this->getText();
 * $this->Text='abc';  // equivalent to $this->setText('abc');
 * </code>
 * The signatures of getter and setter methods are as follows,
 * <code>
 * // getter, defines a readable property 'Text'
 * function getText() { ... }
 * // setter, defines a writable property 'Text', with $value being the value to be set to the property
 * function setText($value) { ... }
 * </code>
 * Property names are case-insensitive. It is recommended that they are written
 * in the format of concatenated words, with the first letter of each word
 * capitalized (e.g. DisplayMode, ItemStyle).
 *
 * An event is defined by the presence of a method whose name starts with 'on'.
 * The event name is the method name and is thus case-insensitive.
 * An event can be attached with one or several methods (called event handlers).
 * An event can be raised by calling {@link raiseEvent} method, upon which
 * the attached event handlers will be invoked automatically in the order they
 * are attached to the event. Event handlers must have the following signature,
 * <code>
 * function eventHandlerFuncName($sender,$param) { ... }
 * </code>
 * where $sender refers to the object who is responsible for the raising of the event,
 * and $param refers to a structure that may contain event-specific information.
 * To raise an event (assuming named as 'Click') of a component, use
 * <code>
 * $component->raiseEvent('OnClick');
 * </code>
 * To attach an event handler to an event, use one of the following ways,
 * <code>
 * $component->OnClick=$callback;  // or $component->OnClick->add($callback);
 * $$component->attachEventHandler('OnClick',$callback);
 * </code>
 * The first two ways make use of the fact that $component->OnClick refers to
 * the event handler list {@link TList} for the 'OnClick' event.
 * The variable $callback contains the definition of the event handler that can
 * be either a string referring to a global function name, or an array whose
 * first element refers to an object and second element a method name/path that
 * is reachable by the object, e.g.
 * - 'buttonClicked' : buttonClicked($sender,$param);
 * - array($object,'buttonClicked') : $object->buttonClicked($sender,$param);
 * - array($object,'MainContent.SubmitButton.buttonClicked') :
 *   $object->MainContent->SubmitButton->buttonClicked($sender,$param);
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: TComponent.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @package System
 * @since 3.0
 */
class TComponent
{
        /**
         * @var array event handler lists
         */
        private $_e=array();

        /**
         * Returns a property value or an event handler list by property or event name.
         * Do not call this method. This is a PHP magic method that we override
         * to allow using the following syntax to read a property:
         * <code>
         * $value=$component->PropertyName;
         * </code>
         * and to obtain the event handler list for an event,
         * <code>
         * $eventHandlerList=$component->EventName;
         * </code>
         * @param string the property name or the event name
         * @return mixed the property value or the event handler list
         * @throws TInvalidOperationException if the property/event is not defined.
         */
        public function __get($name)
        {
                $getter='get'.$name;
                if(method_exists($this,$getter))
                {
                        // getting a property
                        return $this->$getter();
                }
                else if(strncasecmp($name,'on',2)===0 && method_exists($this,$name))
                {
                        // getting an event (handler list)
                        $name=strtolower($name);
                        if(!isset($this->_e[$name]))
                                $this->_e[$name]=new TList;
                        return $this->_e[$name];
                }
                else
                {
                        throw new TInvalidOperationException('component_property_undefined',get_class($this),$name);
                }
        }

        /**
         * Sets value of a component property.
         * Do not call this method. This is a PHP magic method that we override
         * to allow using the following syntax to set a property or attach an event handler.
         * <code>
         * $this->PropertyName=$value;
         * $this->EventName=$handler;
         * </code>
         * @param string the property name or event name
         * @param mixed the property value or event handler
         * @throws TInvalidOperationException If the property is not defined or read-only.
         */
        public function __set($name,$value)
        {
                $setter='set'.$name;
                if(method_exists($this,$setter))
                {
                        $this->$setter($value);
                }
                else if(strncasecmp($name,'on',2)===0 && method_exists($this,$name))
                {
                        $this->attachEventHandler($name,$value);
                }
                else if(method_exists($this,'get'.$name))
                {
                        throw new TInvalidOperationException('component_property_readonly',get_class($this),$name);
                }
                else
                {
                        throw new TInvalidOperationException('component_property_undefined',get_class($this),$name);
                }
        }

        /**
         * Determines whether a property is defined.
         * A property is defined if there is a getter or setter method
         * defined in the class. Note, property names are case-insensitive.
         * @param string the property name
         * @return boolean whether the property is defined
         */
        public function hasProperty($name)
        {
                return method_exists($this,'get'.$name) || method_exists($this,'set'.$name);
        }

        /**
         * Determines whether a property can be read.
         * A property can be read if the class has a getter method
         * for the property name. Note, property name is case-insensitive.
         * @param string the property name
         * @return boolean whether the property can be read
         */
        public function canGetProperty($name)
        {
                return method_exists($this,'get'.$name);
        }

        /**
         * Determines whether a property can be set.
         * A property can be written if the class has a setter method
         * for the property name. Note, property name is case-insensitive.
         * @param string the property name
         * @return boolean whether the property can be written
         */
        public function canSetProperty($name)
        {
                return method_exists($this,'set'.$name);
        }

        /**
         * Evaluates a property path.
         * A property path is a sequence of property names concatenated by '.' character.
         * For example, 'Parent.Page' refers to the 'Page' property of the component's
         * 'Parent' property value (which should be a component also).
         * @param string property path
         * @return mixed the property path value
         */
        public function getSubProperty($path)
        {
                $object=$this;
                foreach(explode('.',$path) as $property)
                        $object=$object->$property;
                return $object;
        }

        /**
         * Sets a value to a property path.
         * A property path is a sequence of property names concatenated by '.' character.
         * For example, 'Parent.Page' refers to the 'Page' property of the component's
         * 'Parent' property value (which should be a component also).
         * @param string property path
         * @param mixed the property path value
         */
        public function setSubProperty($path,$value)
        {
                $object=$this;
                if(($pos=strrpos($path,'.'))===false)
                        $property=$path;
                else
                {
                        $object=$this->getSubProperty(substr($path,0,$pos));
                        $property=substr($path,$pos+1);
                }
                $object->$property=$value;
        }

        /**
         * Determines whether an event is defined.
         * An event is defined if the class has a method whose name is the event name prefixed with 'on'.
         * Note, event name is case-insensitive.
         * @param string the event name
         * @return boolean
         */
        public function hasEvent($name)
        {
                return strncasecmp($name,'on',2)===0 && method_exists($this,$name);
        }

        /**
         * @return boolean whether an event has been attached one or several handlers
         */
        public function hasEventHandler($name)
        {
                $name=strtolower($name);
                return isset($this->_e[$name]) && $this->_e[$name]->getCount()>0;
        }

        /**
         * Returns the list of attached event handlers for an event.
         * @return TList list of attached event handlers for an event
         * @throws TInvalidOperationException if the event is not defined
         */
        public function getEventHandlers($name)
        {
                if(strncasecmp($name,'on',2)===0 && method_exists($this,$name))
                {
                        $name=strtolower($name);
                        if(!isset($this->_e[$name]))
                                $this->_e[$name]=new TList;
                        return $this->_e[$name];
                }
                else
                        throw new TInvalidOperationException('component_event_undefined',get_class($this),$name);
        }

        /**
         * Attaches an event handler to an event.
         *
         * The handler must be a valid PHP callback, i.e., a string referring to
         * a global function name, or an array containing two elements with
         * the first element being an object and the second element a method name
         * of the object. In Prado, you can also use method path to refer to
         * an event handler. For example, array($object,'Parent.buttonClicked')
         * uses a method path that refers to the method $object->Parent->buttonClicked(...).
         *
         * The event handler must be of the following signature,
         * <code>
         * function handlerName($sender,$param) {}
         * </code>
         * where $sender represents the object that raises the event,
         * and $param is the event parameter.
         *
         * This is a convenient method to add an event handler.
         * It is equivalent to {@link getEventHandlers}($name)->add($handler).
         * For complete management of event handlers, use {@link getEventHandlers}
         * to get the event handler list first, and then do various
         * {@link TList} operations to append, insert or remove
         * event handlers. You may also do these operations like
         * getting and setting properties, e.g.,
         * <code>
         * $component->OnClick[]=array($object,'buttonClicked');
         * $component->OnClick->insertAt(0,array($object,'buttonClicked'));
         * </code>
         * which are equivalent to the following
         * <code>
         * $component->getEventHandlers('OnClick')->add(array($object,'buttonClicked'));
         * $component->getEventHandlers('OnClick')->insertAt(0,array($object,'buttonClicked'));
         * </code>
         *
         * @param string the event name
         * @param callback the event handler
         * @throws TInvalidOperationException if the event does not exist
         */
        public function attachEventHandler($name,$handler)
        {
                $this->getEventHandlers($name)->add($handler);
        }

        /**
         * Detaches an existing event handler.
         * This method is the opposite of {@link attachEventHandler}.
         * @param string event name
         * @param callback the event handler to be removed
         * @return boolean if the removal is successful
         */
        public function detachEventHandler($name,$handler)
        {
                if($this->hasEventHandler($name))
                {
                        try
                        {
                                $this->getEventHandlers($name)->remove($handler);
                                return true;
                        }
                        catch(Exception $e)
                        {
                        }
                }
                return false;
        }

        /**
         * Raises an event.
         * This method represents the happening of an event and will
         * invoke all attached event handlers for the event.
         * @param string the event name
         * @param mixed the event sender object
         * @param TEventParameter the event parameter
         * @throws TInvalidOperationException if the event is undefined
         * @throws TInvalidDataValueException If an event handler is invalid
         */
        public function raiseEvent($name,$sender,$param)
        {
                $name=strtolower($name);
                if(isset($this->_e[$name]))
                {
                        foreach($this->_e[$name] as $handler)
                        {
                                if(is_string($handler))
                                {
                                        if(($pos=strrpos($handler,'.'))!==false)
                                        {
                                                $object=$this->getSubProperty(substr($handler,0,$pos));
                                                $method=substr($handler,$pos+1);
                                                if(method_exists($object,$method))
                                                        $object->$method($sender,$param);
                                                else
                                                        throw new TInvalidDataValueException('component_eventhandler_invalid',get_class($this),$name,$handler);
                                        }
                                        else
                                                call_user_func($handler,$sender,$param);
                                }
                                else if(is_callable($handler,true))
                                {
                                        // an array: 0 - object, 1 - method name/path
                                        list($object,$method)=$handler;
                                        if(is_string($object))  // static method call
                                                call_user_func($handler,$sender,$param);
                                        else
                                        {
                                                if(($pos=strrpos($method,'.'))!==false)
                                                {
                                                        $object=$this->getSubProperty(substr($method,0,$pos));
                                                        $method=substr($method,$pos+1);
                                                }
                                                if(method_exists($object,$method))
                                                        $object->$method($sender,$param);
                                                else
                                                        throw new TInvalidDataValueException('component_eventhandler_invalid',get_class($this),$name,$handler[1]);
                                        }
                                }
                                else
                                        throw new TInvalidDataValueException('component_eventhandler_invalid',get_class($this),$name,gettype($handler));
                        }
                }
                else if(!$this->hasEvent($name))
                        throw new TInvalidOperationException('component_event_undefined',get_class($this),$name);
        }

        /**
         * Evaluates a PHP expression in the context of this control.
         * @return mixed the expression result
         * @throws TInvalidOperationException if the expression is invalid
         */
        public function evaluateExpression($expression)
        {
                try
                {
                        if(eval("\$result=$expression;")===false)
                                throw new Exception('');
                        return $result;
                }
                catch(Exception $e)
                {
                        throw new TInvalidOperationException('component_expression_invalid',get_class($this),$expression,$e->getMessage());
                }
        }

        /**
         * Evaluates a list of PHP statements.
         * @param string PHP statements
         * @return string content echoed or printed by the PHP statements
         * @throws TInvalidOperationException if the statements are invalid
         */
        public function evaluateStatements($statements)
        {
                try
                {
                        ob_start();
                        if(eval($statements)===false)
                                throw new Exception('');
                        $content=ob_get_contents();
                        ob_end_clean();
                        return $content;
                }
                catch(Exception $e)
                {
                        throw new TInvalidOperationException('component_statements_invalid',get_class($this),$statements,$e->getMessage());
                }
        }

        /**
         * This method is invoked after the component is instantiated by a template.
         * When this method is invoked, the component's properties have been initialized.
         * The default implementation of this method will invoke
         * the potential parent component's {@link addParsedObject}.
         * This method can be overridden.
         * @param TComponent potential parent of this control
         * @see addParsedObject
         */
        public function createdOnTemplate($parent)
        {
                $parent->addParsedObject($this);
        }

        /**
         * Processes an object that is created during parsing template.
         * The object can be either a component or a static text string.
         * This method can be overridden to customize the handling of newly created objects in template.
         * Only framework developers and control developers should use this method.
         * @param string|TComponent text string or component parsed and instantiated in template
         * @see createdOnTemplate
         */
        public function addParsedObject($object)
        {
        }
}

/**
 * TEnumerable class.
 * TEnumerable is the base class for all enumerable types.
 * To define an enumerable type, extend TEnumberable and define string constants.
 * Each constant represents an enumerable value.
 * The constant name must be the same as the constant value.
 * For example,
 * <code>
 * class TTextAlign extends TEnumerable
 * {
 *     const Left='Left';
 *     const Right='Right';
 * }
 * </code>
 * Then, one can use the enumerable values such as TTextAlign::Left and
 * TTextAlign::Right.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: TComponent.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @package System
 * @since 3.0
 */
class TEnumerable
{
}

/**
 * TPropertyValue class
 *
 * TPropertyValue is a utility class that provides static methods
 * to convert component property values to specific types.
 *
 * TPropertyValue is commonly used in component setter methods to ensure
 * the new property value is of specific type.
 * For example, a boolean-typed property setter method would be as follows,
 * <code>
 * function setPropertyName($value) {
 *     $value=TPropertyValue::ensureBoolean($value);
 *     // $value is now of boolean type
 * }
 * </code>
 *
 * Properties can be of the following types with specific type conversion rules:
 * - string: a boolean value will be converted to 'true' or 'false'.
 * - boolean: string 'true' (case-insensitive) will be converted to true,
 *            string 'false' (case-insensitive) will be converted to false.
 * - integer
 * - float
 * - array: string starting with '(' and ending with ')' will be considered as
 *          as an array expression and will be evaluated. Otherwise, an array
 *          with the value to be ensured is returned.
 * - object
 * - enum: enumerable type, represented by an array of strings.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: TComponent.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @package System
 * @since 3.0
 */
class TPropertyValue
{
        /**
         * Converts a value to boolean type.
         * Note, string 'true' (case-insensitive) will be converted to true,
         * string 'false' (case-insensitive) will be converted to false.
         * If a string represents a non-zero number, it will be treated as true.
         * @param mixed the value to be converted.
         * @return boolean
         */
        public static function ensureBoolean($value)
        {
                if (is_string($value))
                        return strcasecmp($value,'true')==0 || $value!=0;
                else
                        return (boolean)$value;
        }

        /**
         * Converts a value to string type.
         * Note, a boolean value will be converted to 'true' if it is true
         * and 'false' if it is false.
         * @param mixed the value to be converted.
         * @return string
         */
        public static function ensureString($value)
        {
                if (is_bool($value))
                        return $value?'true':'false';
                else
                        return (string)$value;
        }

        /**
         * Converts a value to integer type.
         * @param mixed the value to be converted.
         * @return integer
         */
        public static function ensureInteger($value)
        {
                return (integer)$value;
        }

        /**
         * Converts a value to float type.
         * @param mixed the value to be converted.
         * @return float
         */
        public static function ensureFloat($value)
        {
                return (float)$value;
        }

        /**
         * Converts a value to array type. If the value is a string and it is
         * in the form (a,b,c) then an array consisting of each of the elements
         * will be returned. If the value is a string and it is not in this form
         * then an array consisting of just the string will be returned. If the value
         * is not a string then
         * @param mixed the value to be converted.
         * @return array
         */
        public static function ensureArray($value)
        {
                if(is_string($value))
                {
                        $value = trim($value);
                        $len = strlen($value);
                        if ($len >= 2 && $value[0] == '(' && $value[$len-1] == ')')
                        {
                                eval('$array=array'.$value.';');
                                return $array;
                        }
                        else
                                return $len>0?array($value):array();
                }
                else
                        return (array)$value;
        }

        /**
         * Converts a value to object type.
         * @param mixed the value to be converted.
         * @return object
         */
        public static function ensureObject($value)
        {
                return (object)$value;
        }

        /**
         * Converts a value to enum type.
         *
         * This method checks if the value is of the specified enumerable type.
         * A value is a valid enumerable value if it is equal to the name of a constant
         * in the specified enumerable type (class).
         * For more details about enumerable, see {@link TEnumerable}.
         *
         * For backward compatibility, this method also supports sanity
         * check of a string value to see if it is among the given list of strings.
         * @param mixed the value to be converted.
         * @param mixed class name of the enumerable type, or array of valid enumeration values. If this is not an array,
         * the method considers its parameters are of variable length, and the second till the last parameters are enumeration values.
         * @return string the valid enumeration value
         * @throws TInvalidDataValueException if the original value is not in the string array.
         */
        public static function ensureEnum($value,$enums)
        {
                static $types=array();
                if(func_num_args()===2 && is_string($enums))
                {
                        if(!isset($types[$enums]))
                                $types[$enums]=new ReflectionClass($enums);
                        if($types[$enums]->hasConstant($value))
                                return $value;
                        else
                                throw new TInvalidDataValueException(
                                        'propertyvalue_enumvalue_invalid',$value,
                                                implode(' | ',$types[$enums]->getConstants()));
                }
                else if(!is_array($enums))
                {
                        $enums=func_get_args();
                        array_shift($enums);
                }
                if(in_array($value,$enums,true))
                        return $value;
                else
                        throw new TInvalidDataValueException('propertyvalue_enumvalue_invalid',$value,implode(' | ',$enums));
        }
}

/**
 * TEventParameter class.
 * TEventParameter is the base class for all event parameter classes.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: TComponent.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @package System
 * @since 3.0
 */
class TEventParameter extends TComponent
{
}

/**
 * TComponentReflection class.
 *
 * TComponentReflection provides functionalities to inspect the public/protected
 * properties, events and methods defined in a class.
 *
 * The following code displays the properties and events defined in {@link TDataGrid},
 * <code>
 *   $reflection=new TComponentReflection('TDataGrid');
 *   Prado::varDump($reflection->getProperties());
 *   Prado::varDump($reflection->getEvents());
 * </code>
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: TComponent.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @package System
 * @since 3.0
 */
class TComponentReflection extends TComponent
{
        private $_className;
        private $_properties=array();
        private $_events=array();
        private $_methods=array();

        /**
         * Constructor.
         * @param object|string the component instance or the class name
         * @throws TInvalidDataTypeException if the object is not a component
         */
        public function __construct($component)
        {
                if(is_string($component) && class_exists($component,false))
                        $this->_className=$component;
                else if(is_object($component))
                        $this->_className=get_class($component);
                else
                        throw new TInvalidDataTypeException('componentreflection_class_invalid');
                $this->reflect();
        }

        private function isPropertyMethod($method)
        {
                $methodName=$method->getName();
                return $method->getNumberOfRequiredParameters()===0
                                && strncasecmp($methodName,'get',3)===0
                                && isset($methodName[3]);
        }

        private function isEventMethod($method)
        {
                $methodName=$method->getName();
                return strncasecmp($methodName,'on',2)===0
                                && isset($methodName[2]);
        }

        private function reflect()
        {
                $class=new TReflectionClass($this->_className);
                $properties=array();
                $events=array();
                $methods=array();
                $isComponent=is_subclass_of($this->_className,'TComponent') || strcasecmp($this->_className,'TComponent')===0;
                foreach($class->getMethods() as $method)
                {
                        if($method->isPublic() || $method->isProtected())
                        {
                                $methodName=$method->getName();
                                if(!$method->isStatic() && $isComponent)
                                {
                                        if($this->isPropertyMethod($method))
                                                $properties[substr($methodName,3)]=$method;
                                        else if($this->isEventMethod($method))
                                        {
                                                $methodName[0]='O';
                                                $events[$methodName]=$method;
                                        }
                                }
                                if(strncmp($methodName,'__',2)!==0)
                                        $methods[$methodName]=$method;
                        }
                }
                $reserved=array();
                ksort($properties);
                foreach($properties as $name=>$method)
                {
                        $this->_properties[$name]=array(
                                'type'=>$this->determinePropertyType($method),
                                'readonly'=>!$class->hasMethod('set'.$name),
                                'protected'=>$method->isProtected(),
                                'class'=>$method->getDeclaringClass()->getName(),
                                'comments'=>$method->getDocComment()
                        );
                        $reserved['get'.strtolower($name)]=1;
                        $reserved['set'.strtolower($name)]=1;
                }
                ksort($events);
                foreach($events as $name=>$method)
                {
                        $this->_events[$name]=array(
                                'class'=>$method->getDeclaringClass()->getName(),
                                'protected'=>$method->isProtected(),
                                'comments'=>$method->getDocComment()
                        );
                        $reserved[strtolower($name)]=1;
                }
                ksort($methods);
                foreach($methods as $name=>$method)
                {
                        if(!isset($reserved[strtolower($name)]))
                                $this->_methods[$name]=array(
                                        'class'=>$method->getDeclaringClass()->getName(),
                                        'protected'=>$method->isProtected(),
                                        'static'=>$method->isStatic(),
                                        'comments'=>$method->getDocComment()
                                );
                }
        }

        /**
         * Determines the property type.
         * This method uses the doc comment to determine the property type.
         * @param ReflectionMethod
         * @return string the property type, '{unknown}' if type cannot be determined from comment
         */
        protected function determinePropertyType($method)
        {
                $comment=$method->getDocComment();
                if(preg_match('/@return\\s+(.*?)\\s+/',$comment,$matches))
                        return $matches[1];
                else
                        return '{unknown}';
        }

        /**
         * @return string class name of the component
         */
        public function getClassName()
        {
                return $this->_className;
        }

        /**
         * @return array list of component properties. Array keys are property names.
         * Each array element is of the following structure:
         * [type]=>property type,
         * [readonly]=>whether the property is read-only,
         * [protected]=>whether the method is protected or not
         * [class]=>the class where the property is inherited from,
         * [comments]=>comments associated with the property.
         */
        public function getProperties()
        {
                return $this->_properties;
        }

        /**
         * @return array list of component events. Array keys are event names.
         * Each array element is of the following structure:
         * [protected]=>whether the event is protected or not
         * [class]=>the class where the event is inherited from.
         * [comments]=>comments associated with the event.
         */
        public function getEvents()
        {
                return $this->_events;
        }

        /**
         * @return array list of public/protected methods. Array keys are method names.
         * Each array element is of the following structure:
         * [protected]=>whether the method is protected or not
         * [static]=>whether the method is static or not
         * [class]=>the class where the property is inherited from,
         * [comments]=>comments associated with the event.
         */
        public function getMethods()
        {
                return $this->_methods;
        }
}