0 follower

CComponent

Package system.base
Inheritance class CComponent
Subclasses CAccessRule, CAction, CActiveFinder, CApplicationComponent, CAuthAssignment, CAuthItem, CBaseActiveRelation, CBaseController, CBaseUrlRule, CBaseUserIdentity, CBehavior, CCacheDependency, CChainedCacheDependency, CChainedLogFilter, CCodeFile, CConsoleCommand, CConsoleCommandRunner, CDataProvider, CDataProviderIterator, CDateFormatter, CDbColumnSchema, CDbCommand, CDbCommandBuilder, CDbCriteria, CDbDataReader, CDbExpression, CDbMigration, CDbSchema, CDbTableSchema, CDbTransaction, CEvent, CFilter, CFormElement, CGettextFile, CGridColumn, CHttpCookie, CList, CLocale, CLogFilter, CLogRoute, CLogger, CMap, CMemCacheServerConfiguration, CModel, CModule, CNumberFormatter, CPagination, CQueue, CSort, CStack, CTheme, CUploadedFile, CValidator, CWebService, CWsdlGenerator
Since 1.0
Source Code framework/base/CComponent.php
CComponent is the base class for all components.

CComponent 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=$component->text;     // equivalent to $a=$component->getText();
$component->text='abc';  // equivalent to $component->setText('abc');
The signatures of getter and setter methods are as follows,
// getter, defines a readable property 'text'
public function getText() { ... }
// setter, defines a writable property 'text' with $value to be set to the property
public function setText($value) { ... }


An event is defined by the presence of a method whose name starts with 'on'. The event name is the method name. When an event is raised, functions (called event handlers) attached to the event will be invoked automatically.

An event can be raised by calling 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 eventHandler($event) { ... }
where $event includes parameters associated with the event.

To attach an event handler to an event, see attachEventHandler. You can also use the following syntax:
$component->onClick=$callback;    // or $component->onClick->add($callback);
where $callback refers to a valid PHP callback. Below we show some callback examples:
'handleOnClick'                   // handleOnClick() is a global function
array($object,'handleOnClick')    // using $object->handleOnClick()
array('Page','handleOnClick')     // using Page::handleOnClick()


To raise an event, use raiseEvent. The on-method defining an event is commonly written like the following:
public function onClick($event)
{
    $this->raiseEvent('onClick',$event);
}
where $event is an instance of CEvent or its child class. One can then raise the event by calling the on-method instead of raiseEvent directly.

Both property names and event names are case-insensitive.

CComponent supports behaviors. A behavior is an instance of IBehavior which is attached to a component. The methods of the behavior can be invoked as if they belong to the component. Multiple behaviors can be attached to the same component.

To attach a behavior to a component, call attachBehavior; and to detach the behavior from the component, call detachBehavior.

A behavior can be temporarily enabled or disabled by calling enableBehavior or disableBehavior, respectively. When disabled, the behavior methods cannot be invoked via the component.

Starting from version 1.1.0, a behavior's properties (either its public member variables or its properties defined via getters and/or setters) can be accessed through the component it is attached to.

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
raiseEvent() Raises an event. CComponent

Method Details

__call() method
public mixed __call(string $name, array $parameters)
$name string the method name
$parameters array method parameters
{return} mixed the method return value
Source Code: framework/base/CComponent.php#254 (show)
public function __call($name,$parameters)
{
    if(
$this->_m!==null)
    {
        foreach(
$this->_m as $object)
        {
            if(
$object->getEnabled() && method_exists($object,$name))
                return 
call_user_func_array(array($object,$name),$parameters);
        }
    }
    if(
class_exists('Closure'false) && ($this->canGetProperty($name) || property_exists($this$name)) && $this->$name instanceof Closure)
        return 
call_user_func_array($this->$name$parameters);
    throw new 
CException(Yii::t('yii','{class} and its behaviors do not have a method or closure named "{name}".',
        array(
'{class}'=>get_class($this), '{name}'=>$name)));
}

Calls the named method which is not a class method. Do not call this method. This is a PHP magic method that we override to implement the behavior feature.

__get() method
public mixed __get(string $name)
$name string the property name or event name
{return} mixed the property value, event handlers attached to the event, or the named behavior
Source Code: framework/base/CComponent.php#107 (show)
public function __get($name)
{
    
$getter='get'.$name;
    if(
method_exists($this,$getter))
        return 
$this->$getter();
    elseif(
strncasecmp($name,'on',2)===&& method_exists($this,$name))
    {
        
// duplicating getEventHandlers() here for performance
        
$name=strtolower($name);
        if(!isset(
$this->_e[$name]))
            
$this->_e[$name]=new CList;
        return 
$this->_e[$name];
    }
    elseif(isset(
$this->_m[$name]))
        return 
$this->_m[$name];
    elseif(
is_array($this->_m))
    {
        foreach(
$this->_m as $object)
        {
            if(
$object->getEnabled() && (property_exists($object,$name) || $object->canGetProperty($name)))
                return 
$object->$name;
        }
    }
    throw new 
CException(Yii::t('yii','Property "{class}.{property}" is not defined.',
        array(
'{class}'=>get_class($this), '{property}'=>$name)));
}

Returns a property value, an event handler list or a behavior based on its 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 or obtain event handlers:

$value=$component->propertyName;
$handlers=$component->eventName;

See Also

__isset() method
public boolean __isset(string $name)
$name string the property name or the event name
{return} boolean
Source Code: framework/base/CComponent.php#184 (show)
public function __isset($name)
{
    
$getter='get'.$name;
    if(
method_exists($this,$getter))
        return 
$this->$getter()!==null;
    elseif(
strncasecmp($name,'on',2)===&& method_exists($this,$name))
    {
        
$name=strtolower($name);
        return isset(
$this->_e[$name]) && $this->_e[$name]->getCount();
    }
    elseif(
is_array($this->_m))
    {
         if(isset(
$this->_m[$name]))
             return 
true;
        foreach(
$this->_m as $object)
        {
            if(
$object->getEnabled() && (property_exists($object,$name) || $object->canGetProperty($name)))
                return 
$object->$name!==null;
        }
    }
    return 
false;
}

Checks if a property value is null. Do not call this method. This is a PHP magic method that we override to allow using isset() to detect if a component property is set or not.

__set() method
public mixed __set(string $name, mixed $value)
$name string the property name or the event name
$value mixed the property value or callback
{return} mixed
Source Code: framework/base/CComponent.php#148 (show)
public function __set($name,$value)
{
    
$setter='set'.$name;
    if(
method_exists($this,$setter))
        return 
$this->$setter($value);
    elseif(
strncasecmp($name,'on',2)===&& method_exists($this,$name))
    {
        
// duplicating getEventHandlers() here for performance
        
$name=strtolower($name);
        if(!isset(
$this->_e[$name]))
            
$this->_e[$name]=new CList;
        return 
$this->_e[$name]->add($value);
    }
    elseif(
is_array($this->_m))
    {
        foreach(
$this->_m as $object)
        {
            if(
$object->getEnabled() && (property_exists($object,$name) || $object->canSetProperty($name)))
                return 
$object->$name=$value;
        }
    }
    if(
method_exists($this,'get'.$name))
        throw new 
CException(Yii::t('yii','Property "{class}.{property}" is read only.',
            array(
'{class}'=>get_class($this), '{property}'=>$name)));
    else
        throw new 
CException(Yii::t('yii','Property "{class}.{property}" is not defined.',
            array(
'{class}'=>get_class($this), '{property}'=>$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=$callback;

See Also

__unset() method
public mixed __unset(string $name)
$name string the property name or the event name
{return} mixed
Source Code: framework/base/CComponent.php#215 (show)
public function __unset($name)
{
    
$setter='set'.$name;
    if(
method_exists($this,$setter))
        
$this->$setter(null);
    elseif(
strncasecmp($name,'on',2)===&& method_exists($this,$name))
        unset(
$this->_e[strtolower($name)]);
    elseif(
is_array($this->_m))
    {
        if(isset(
$this->_m[$name]))
            
$this->detachBehavior($name);
        else
        {
            foreach(
$this->_m as $object)
            {
                if(
$object->getEnabled())
                {
                    if(
property_exists($object,$name))
                        return 
$object->$name=null;
                    elseif(
$object->canSetProperty($name))
                        return 
$object->$setter(null);
                }
            }
        }
    }
    elseif(
method_exists($this,'get'.$name))
        throw new 
CException(Yii::t('yii','Property "{class}.{property}" is read only.',
            array(
'{class}'=>get_class($this), '{property}'=>$name)));
}

Sets a component property to be null. Do not call this method. This is a PHP magic method that we override to allow using unset() to set a component property to be null.

asa() method
public IBehavior asa(string $behavior)
$behavior string the behavior name
{return} IBehavior the behavior object, or null if the behavior does not exist
Source Code: framework/base/CComponent.php#276 (show)
public function asa($behavior)
{
    return isset(
$this->_m[$behavior]) ? $this->_m[$behavior] : null;
}

Returns the named behavior object. The name 'asa' stands for 'as a'.

attachBehavior() method
public IBehavior attachBehavior(string $name, mixed $behavior)
$name string the behavior's name. It should uniquely identify this behavior.
$behavior mixed the behavior configuration. This is passed as the first parameter to YiiBase::createComponent to create the behavior object. You can also pass an already created behavior instance (the new behavior will replace an already created behavior with the same name, if it exists).
{return} IBehavior the behavior object
Source Code: framework/base/CComponent.php#326 (show)
public function attachBehavior($name,$behavior)
{
    if(!(
$behavior instanceof IBehavior))
        
$behavior=Yii::createComponent($behavior);
    
$behavior->setEnabled(true);
    
$behavior->attach($this);
    return 
$this->_m[$name]=$behavior;
}

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 IBehavior::attach method.

attachBehaviors() method
public void attachBehaviors(array $behaviors)
$behaviors array list of behaviors to be attached to the component
Source Code: framework/base/CComponent.php#295 (show)
public function attachBehaviors($behaviors)
{
    foreach(
$behaviors as $name=>$behavior)
        
$this->attachBehavior($name,$behavior);
}

Attaches a list of behaviors to the component. Each behavior is indexed by its name and should be an instance of IBehavior, a string specifying the behavior class, or an array of the following structure:

array(
    'class'=>'path.to.BehaviorClass',
    'property1'=>'value1',
    'property2'=>'value2',
)
attachEventHandler() method
public void attachEventHandler(string $name, callback $handler)
$name string the event name
$handler callback the event handler
Source Code: framework/base/CComponent.php#514 (show)
public function attachEventHandler($name,$handler)
{
    
$this->getEventHandlers($name)->add($handler);
}

Attaches an event handler to an event.

An event 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.

An event handler must be defined with the following signature,

function handlerName($event) {}
where $event includes parameters associated with the event.

This is a convenient method of attaching a handler to an event. It is equivalent to the following code:
$component->getEventHandlers($eventName)->add($eventHandler);


Using getEventHandlers, one can also specify the execution order of multiple handlers attaching to the same event. For example:
$component->getEventHandlers($eventName)->insertAt(0,$eventHandler);
makes the handler to be invoked first.
canGetProperty() method
public boolean canGetProperty(string $name)
$name string the property name
{return} boolean whether the property can be read
Source Code: framework/base/CComponent.php#421 (show)
public function canGetProperty($name)
{
    return 
method_exists($this,'get'.$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.

See Also

canSetProperty() method
public boolean canSetProperty(string $name)
$name string the property name
{return} boolean whether the property can be written
Source Code: framework/base/CComponent.php#434 (show)
public function canSetProperty($name)
{
    return 
method_exists($this,'set'.$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.

See Also

detachBehavior() method
public IBehavior detachBehavior(string $name)
$name string the behavior's name. It uniquely identifies the behavior.
{return} IBehavior the detached behavior. Null if the behavior does not exist.
Source Code: framework/base/CComponent.php#341 (show)
public function detachBehavior($name)
{
    if(isset(
$this->_m[$name]))
    {
        
$this->_m[$name]->detach($this);
        
$behavior=$this->_m[$name];
        unset(
$this->_m[$name]);
        return 
$behavior;
    }
}

Detaches a behavior from the component. The behavior's IBehavior::detach method will be invoked.

detachBehaviors() method
public void detachBehaviors()
Source Code: framework/base/CComponent.php#304 (show)
public function detachBehaviors()
{
    if(
$this->_m!==null)
    {
        foreach(
$this->_m as $name=>$behavior)
            
$this->detachBehavior($name);
        
$this->_m=null;
    }
}

Detaches all behaviors from the component.

detachEventHandler() method
public boolean detachEventHandler(string $name, callback $handler)
$name string event name
$handler callback the event handler to be removed
{return} boolean if the detachment process is successful
Source Code: framework/base/CComponent.php#527 (show)
public function detachEventHandler($name,$handler)
{
    if(
$this->hasEventHandler($name))
        return 
$this->getEventHandlers($name)->remove($handler)!==false;
    else
        return 
false;
}

Detaches an existing event handler. This method is the opposite of attachEventHandler.

disableBehavior() method
public void disableBehavior(string $name)
$name string the behavior's name. It uniquely identifies the behavior.
Source Code: framework/base/CComponent.php#393 (show)
public function disableBehavior($name)
{
    if(isset(
$this->_m[$name]))
        
$this->_m[$name]->setEnabled(false);
}

Disables an attached behavior. A behavior is only effective when it is enabled.

disableBehaviors() method
public void disableBehaviors()
Source Code: framework/base/CComponent.php#367 (show)
public function disableBehaviors()
{
    if(
$this->_m!==null)
    {
        foreach(
$this->_m as $behavior)
            
$behavior->setEnabled(false);
    }
}

Disables all behaviors attached to this component.

enableBehavior() method
public void enableBehavior(string $name)
$name string the behavior's name. It uniquely identifies the behavior.
Source Code: framework/base/CComponent.php#382 (show)
public function enableBehavior($name)
{
    if(isset(
$this->_m[$name]))
        
$this->_m[$name]->setEnabled(true);
}

Enables an attached behavior. A behavior is only effective when it is enabled. A behavior is enabled when first attached.

enableBehaviors() method
public void enableBehaviors()
Source Code: framework/base/CComponent.php#355 (show)
public function enableBehaviors()
{
    if(
$this->_m!==null)
    {
        foreach(
$this->_m as $behavior)
            
$behavior->setEnabled(true);
    }
}

Enables all behaviors attached to this component.

evaluateExpression() method (available since v1.1.0)
public mixed evaluateExpression(mixed $_expression_, array $_data_=array ( ))
$_expression_ mixed a PHP expression or PHP callback to be evaluated.
$_data_ array additional parameters to be passed to the above expression/callback.
{return} mixed the expression result
Source Code: framework/base/CComponent.php#607 (show)
public function evaluateExpression($_expression_,$_data_=array())
{
    if(
is_string($_expression_))
    {
        
extract($_data_);
        try
        {
            return eval(
'return ' $_expression_ ';');
        }
        catch (
ParseError $e)
        {
            return 
false;
        }
    }
    else
    {
        
$_data_[]=$this;
        return 
call_user_func_array($_expression_array_values($_data_));
    }
}

Evaluates a PHP expression or callback under the context of this component.

Valid PHP callback can be class method name in the form of array(ClassName/Object, MethodName), or anonymous function (only available in PHP 5.3.0 or above).

If a PHP callback is used, the corresponding function/method signature should be

function foo($param1, $param2, ..., $component) { ... }
where the array elements in the second parameter to this method will be passed to the callback as $param1, $param2, ...; and the last parameter will be the component itself.

If a PHP expression is used, the second parameter will be "extracted" into PHP variables that can be directly accessed in the expression. See PHP extract for more details. In the expression, the component object can be accessed using $this.

A PHP expression can be any PHP code that has a value. To learn more about what an expression is, please refer to the php manual.
getEventHandlers() method
public CList getEventHandlers(string $name)
$name string the event name
{return} CList list of attached event handlers for the event
Source Code: framework/base/CComponent.php#468 (show)
public function getEventHandlers($name)
{
    if(
$this->hasEvent($name))
    {
        
$name=strtolower($name);
        if(!isset(
$this->_e[$name]))
            
$this->_e[$name]=new CList;
        return 
$this->_e[$name];
    }
    else
        throw new 
CException(Yii::t('yii','Event "{class}.{event}" is not defined.',
            array(
'{class}'=>get_class($this), '{event}'=>$name)));
}

Returns the list of attached event handlers for an event.

hasEvent() method
public boolean hasEvent(string $name)
$name string the event name
{return} boolean whether an event is defined
Source Code: framework/base/CComponent.php#446 (show)
public function hasEvent($name)
{
    return !
strncasecmp($name,'on',2) && method_exists($this,$name);
}

Determines whether an event is defined. An event is defined if the class has a method named like 'onXXX'. Note, event name is case-insensitive.

hasEventHandler() method
public boolean hasEventHandler(string $name)
$name string the event name
{return} boolean whether an event has been attached one or several handlers
Source Code: framework/base/CComponent.php#456 (show)
public function hasEventHandler($name)
{
    
$name=strtolower($name);
    return isset(
$this->_e[$name]) && $this->_e[$name]->getCount()>0;
}

Checks whether the named event has attached handlers.

hasProperty() method
public boolean hasProperty(string $name)
$name string the property name
{return} boolean whether the property is defined
Source Code: framework/base/CComponent.php#408 (show)
public function hasProperty($name)
{
    return 
method_exists($this,'get'.$name) || method_exists($this,'set'.$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.

raiseEvent() method
public void raiseEvent(string $name, CEvent $event)
$name string the event name
$event CEvent the event parameter
Source Code: framework/base/CComponent.php#543 (show)
public function raiseEvent($name,$event)
{
    
$name=strtolower($name);
    if(isset(
$this->_e[$name]))
    {
        foreach(
$this->_e[$name] as $handler)
        {
            if(
is_string($handler))
                
call_user_func($handler,$event);
            elseif(
is_callable($handler,true))
            {
                if(
is_array($handler))
                {
                    
// an array: 0 - object, 1 - method name
                    
list($object,$method)=$handler;
                    if(
is_string($object))    // static method call
                        
call_user_func($handler,$event);
                    elseif(
method_exists($object,$method))
                        
$object->$method($event);
                    else
                        throw new 
CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".',
                            array(
'{class}'=>get_class($this), '{event}'=>$name'{handler}'=>$handler[1])));
                }
                else 
// PHP 5.3: anonymous function
                    
call_user_func($handler,$event);
            }
            else
                throw new 
CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".',
                    array(
'{class}'=>get_class($this), '{event}'=>$name'{handler}'=>gettype($handler))));
            
// stop further handling if param.handled is set true
            
if(($event instanceof CEvent) && $event->handled)
                return;
        }
    }
    elseif(
YII_DEBUG && !$this->hasEvent($name))
        throw new 
CException(Yii::t('yii','Event "{class}.{event}" is not defined.',
            array(
'{class}'=>get_class($this), '{event}'=>$name)));
}

Raises an event. This method represents the happening of an event. It invokes all attached handlers for the event.