* @link http://www.pradosoft.com/
* @copyright Copyright © 2005-2008 PradoSoft
* @license http://www.pradosoft.com/license/
* @version $Id$
* @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.,
*
* $a=$this->Text; // equivalent to $a=$this->getText();
* $this->Text='abc'; // equivalent to $this->setText('abc');
*
* The signatures of getter and setter methods are as follows,
*
* // 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) { ... }
*
* 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,
*
* function eventHandlerFuncName($sender,$param) { ... }
*
* 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
*
* $component->raiseEvent('OnClick');
*
* To attach an event handler to an event, use one of the following ways,
*
* $component->OnClick=$callback; // or $component->OnClick->add($callback);
* $$component->attachEventHandler('OnClick',$callback);
*
* 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
* @version $Id$
* @package System
* @since 3.0
*/
class TComponent
{
/**
* @var array event handler lists
*/
private $_e=array();
/**
* @var array models (ported from Yii)
*/
private $_m=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:
*
* $value=$component->PropertyName;
*
* and to obtain the event handler list for an event,
*
* $eventHandlerList=$component->EventName;
*
* @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.
*
* $this->PropertyName=$value;
* $this->EventName=$handler;
*
* @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,
*
* function handlerName($sender,$param) {}
*
* 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.,
*
* $component->OnClick[]=array($object,'buttonClicked');
* $component->OnClick->insertAt(0,array($object,'buttonClicked'));
*
* which are equivalent to the following
*
* $component->getEventHandlers('OnClick')->add(array($object,'buttonClicked'));
* $component->getEventHandlers('OnClick')->insertAt(0,array($object,'buttonClicked'));
*
*
* @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)
{
}
/**
* Returns the named behavior object.
* The name 'asa' stands for 'as a'.
* @param string the behavior name
* @return IBehavior the behavior object, or null if the behavior does not exist
*/
public function asa($behavior)
{
return isset($this->_m[$behavior]) ? $this->_m[$behavior] : null;
}
/**
* Attaches a list of behaviors to the component.
* Each behavior is indexed by its name and should be an instance of
* {@link IBehavior}, a string specifying the behavior class, or an
* array of the following structure:
*
* array(
* 'class'=>'path.to.BehaviorClass',
* 'property1'=>'value1',
* 'property2'=>'value2',
* )
*
* @param array list of behaviors to be attached to the component
*/
public function attachBehaviors($behaviors)
{
foreach($behaviors as $name=>$behavior)
$this->attachBehavior($name,$behavior);
}
/**
* Detaches all behaviors from the component.
*/
public function detachBehaviors()
{
if($this->_m!==null)
{
foreach($this->_m as $name=>$behavior)
$this->detachBehavior($name);
$this->_m=null;
}
}
/**
* Attaches a behavior to this component.
* This method will create the behavior object based on the given
* configuration. After that, the behavior object will be initialized
* by calling its {@link IBehavior::attach} method.
* @param string the behavior's name. It should uniquely identify this behavior.
* @param mixed the behavior configuration. This is passed as the first
* parameter to {@link YiiBase::createComponent} to create the behavior object.
* @return IBehavior the behavior object
*/
public function attachBehavior($name,$behavior)
{
if(!($behavior instanceof IBehavior))
$behavior=Yii::createComponent($behavior);
$behavior->setEnabled(true);
$behavior->attach($this);
return $this->_m[$name]=$behavior;
}
/**
* Detaches a behavior from the component.
* The behavior's {@link IBehavior::detach} method will be invoked.
* @param string the behavior's name. It uniquely identifies the behavior.
* @return IBehavior the detached behavior. Null if the behavior does not exist.
*/
public function detachBehavior($name)
{
if(isset($this->_m[$name]))
{
$this->_m[$name]->detach($this);
$behavior=$this->_m[$name];
unset($this->_m[$name]);
return $behavior;
}
}
/**
* Enables all behaviors attached to this component.
*/
public function enableBehaviors()
{
if($this->_m!==null)
{
foreach($this->_m as $behavior)
$behavior->setEnabled(true);
}
}
/**
* Disables all behaviors attached to this component.
*/
public function disableBehaviors()
{
if($this->_m!==null)
{
foreach($this->_m as $behavior)
$behavior->setEnabled(false);
}
}
/**
* Enables an attached behavior.
* A behavior is only effective when it is enabled.
* A behavior is enabled when first attached.
* @param string the behavior's name. It uniquely identifies the behavior.
*/
public function enableBehavior($name)
{
if(isset($this->_m[$name]))
$this->_m[$name]->setEnabled(true);
}
/**
* Disables an attached behavior.
* A behavior is only effective when it is enabled.
* @param string the behavior's name. It uniquely identifies the behavior.
*/
public function disableBehavior($name)
{
if(isset($this->_m[$name]))
$this->_m[$name]->setEnabled(false);
}
}
/**
* 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,
*
* class TTextAlign extends TEnumerable
* {
* const Left='Left';
* const Right='Right';
* }
*
* Then, one can use the enumerable values such as TTextAlign::Left and
* TTextAlign::Right.
*
* @author Qiang Xue
* @version $Id$
* @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,
*
* function setPropertyName($value) {
* $value=TPropertyValue::ensureBoolean($value);
* // $value is now of boolean type
* }
*
*
* 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
* @version $Id$
* @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
* @version $Id$
* @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},
*
* $reflection=new TComponentReflection('TDataGrid');
* Prado::varDump($reflection->getProperties());
* Prado::varDump($reflection->getEvents());
*
*
* @author Qiang Xue
* @version $Id$
* @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;
}
}