Component

Yii applications are built upon components which are objects written to a specification. A component is an instance of CComponent or its derived class. Using a component mainly involves accessing its properties and raising/handling its events. The base class CComponent specifies how to define properties and events.

1. Defining and using a Component Property

A component property is like an object's public member variable. We can read its value or assign a value to it. For example,

$width=$component->textWidth;     // get the textWidth property
$component->enableCaching=true;   // set the enableCaching property

There are two different ways of defining a component property. First way is to simply declare a public member variable in the component class like the following:

class Document extends CComponent
{
    public $textWidth;
}

Another way is to use getters and setters. It is more flexible since additionally to normal properties you can declare a read only or write only property.

class Document extends CComponent
{
    private $_textWidth;
    protected $_completed=false;
 
    public function getTextWidth()
    {
        return $this->_textWidth;
    }
 
    public function setTextWidth($value)
    {
        $this->_textWidth=$value;
    }
 
    public function getTextHeight()
    {
        // calculates and returns text height
    }
 
    public function setCompleted($value)
    {
        $this->_completed=$value;
    }
}

The component above can be used like the following:

$document=new Document();
 
// we can write and read textWidth
$document->textWidth=100;
echo $document->textWidth;
 
// we can only read textHeight
echo $document->textHeight;
 
// we can only write completed
$document->completed=true;

When trying to read a component property and the property isn't defined as a public class member, Yii is trying to use a getter method i.e. for textWidth a getter method will be getTextWidth. Same thing happens when trying to write a property not defined as a public class member.

If there's a getter method but no setter method the component property becomes read only and throws an exception if we're trying to write it. If it's the other way around, the property is write-only.

Using getter and setter methods to define a property has the benefit that additional logic (e.g. performing validation, raising events) can be executed when reading and writing the property.

Note: There is a slight difference between a property defined via getter/setter methods and a class member variable. The name of the former is case-insensitive while the latter is case-sensitive.

2. Component Event

Component events are special properties that take methods (called event handlers) as their values. Attaching (assigning) a method to an event will cause the method to be invoked automatically at the places where the event is raised. Therefore, the behavior of a component can be modified in a way that may not be foreseen during the development of the component.

A component event is defined by defining a method whose name starts with on. Like property names defined via getter/setter methods, event names are case-insensitive. The following code defines an onClicked event:

public function onClicked($event)
{
    $this->raiseEvent('onClicked', $event);
}

where $event is an instance of CEvent or its child class representing the event parameter.

We can attach a method to this event as follows:

$component->onClicked=$callback;

where $callback refers to a valid PHP callback. It can be a global function or a class method. If the latter, the callback must be given as an array: array($object,'methodName').

The signature of an event handler must be as follows:

function methodName($event)
{
    ......
}

where $event is the parameter describing the event (it originates from the raiseEvent() call). The $event parameter is an instance of CEvent or its derived class. At the minimum, it contains the information about who raises the event.

An event handler can also be an anonymous function which is supported by PHP 5.3 or above. For example,

$component->onClicked=function($event) {
    ......
}

If we call onClicked() now, the onClicked event will be raised (inside onClicked()), and the attached event handler will be invoked automatically.

An event can be attached with multiple handlers. When the event is raised, the handlers will be invoked in the order that they are attached to the event. If a handler decides to prevent the rest of the handlers from being invoked, it can set $event->handled to be true.

3. Component Behavior

A component supports the mixin pattern and can be attached with one or several behaviors. A behavior is an object whose methods can be 'inherited' by its attached component through the means of collecting functionality instead of specialization (i.e., normal class inheritance). A component can be attached with several behaviors and thus achieve 'multiple inheritance'.

Behavior classes must implement the IBehavior interface. Most behaviors can extend from the CBehavior base class. If a behavior needs to be attached to a model, it may also extend from CModelBehavior or CActiveRecordBehavior which implements additional features specific for models.

To use a behavior, it must be attached to a component first by calling the behavior's attach() method. Then we can call a behavior method via the component:

// $name uniquely identifies the behavior in the component
$component->attachBehavior($name,$behavior);
// test() is a method of $behavior
$component->test();

An attached behavior can be accessed like a normal property of the component. For example, if a behavior named tree is attached to a component, we can obtain the reference to this behavior object using:

$behavior=$component->tree;
// equivalent to the following:
// $behavior=$component->asa('tree');

A behavior can be temporarily disabled so that its methods are not available via the component. For example,

$component->disableBehavior($name);
// the following statement will throw an exception
$component->test();
$component->enableBehavior($name);
// it works now
$component->test();

It is possible that two behaviors attached to the same component have methods of the same name. In this case, the method of the first attached behavior will take precedence.

When used together with events, behaviors are even more powerful. A behavior, when being attached to a component, can attach some of its methods to some events of the component. By doing so, the behavior gets a chance to observe or change the normal execution flow of the component.

A behavior's properties can also be accessed via the component it is attached to. The properties include both the public member variables and the properties defined via getters and/or setters of the behavior. For example, if a behavior has a property named xyz and the behavior is attached to a component $a. Then we can use the expression $a->xyz to access the behavior's property.

$Id$

Total 5 comments

#5691 report it
pligor at 2011/11/02 05:10am
variable precedence using behaviors

if an attribute $var is defined both in behavior and model, model's value takes precedence For example if inside model $var=100; and inside behavior $var=50 then $this->var returns 100

#5406 report it
pligor at 2011/10/10 06:49am
method_exists

Note: some functions like method_exists will NOT return true for behavior's methods

#3900 report it
Dom y Nick at 2011/05/19 06:18am
Correction to "Virtual properties differences"

There is a slight inaccuracy in KJedi's post #1909

You Can actually use isset() on a virtual property, as long as the class properly overloads its behaviour via its private __isset(string) member function (see PHP manual for explanations). And this is actually exactly what the CComponent class does. So, the only thing you can't actually do with virtual properties is check them with empty(); and if you check them with property_exists(class,property) the return value will be FALSE...

#226 report it
Bruce Lee at 2010/08/04 05:54pm
Abstract examples ...

in order to resolve any problem, mathematicians decompose this problem into several smaller problems, because they are more easy to understand and to resolve step by step. Ecquivalent of this math example is our project, which can be decompose also into several modules, but modules can be decompose into several smaller subsystems, which are named components. By this algorithm of decomposition we can easy and efficiently maintain any kind of scaled projects. I hope this description will help you to clearly imagine this easy way.

http://www.yiiframework.com/doc/guide/basics.module A module is a self-contained software unit that consists of models, views, controllers and other supporting components. In many aspects, a module resembles to an application.

P.S.: sorry for my bad english.

#1909 report it
KJedi at 2008/12/17 07:13am
Virtual properties differences

There is one thing you should remember when defining virtual property using getter and setter like in example with textWidth.

You'll be able to write

$component->textWidth = $width

and

$width = $component->textWidth

But you can't use it in construction like empty() or isset(). Why? Reason is simple. Both functions require a variable, and writing

$component->textWidth;

you're calling your

public function getTextWidth()
{
    return $this->_textWidth;
}

So this is not a variable, this is result of function call! You can't pass it by reference, can't get or change it's name (like for normal variable):

$a = $$abc;//$a now holds a string abc
$$abc = 'a';//now we can write $a and it is the same as $abc was. 
// It's not the reference, just changed the variable name.

Please note the main thing - virtual properties are not variables, and write your code understanding this. Good luck!

Leave a comment

Please to leave your comment.