Yii 1.1 Application Development Cookbook

To use getters and setters like properties, CComponent uses the PHP magic methods: __get, __set, __isset, and __unset (http://php.net/manual/en/language.oop5.magic.php). The following example shows what Yii 1.1 CComponent::__get looks like:

public function __get($name)
{
   $getter='get'.$name;
   if(method_exists($this,$getter))
      return $this->$getter();
…

This magic PHP method intercepts all calls to missing real properties, so when we are calling $myClass->property, it receives property as $name parameter. If a method named getProperty exists, then PHP uses its return value as a property value.

For further information, refer to the following URL:

http://www.php.net/manual/en/language.oop5.overloading.php#language.oop5.overloading.members

To declare an event in your CComponent child class, you should add a method with a name starting with on. For example, if you add the onRegister method, you will get a corresponding event declared.

Typically, events are used like this:

Let's look at how we can attach an event handler to an event. To achieve it, we can use the CComponent::attachEventHandler method. It accepts the following two parameters:

In PHP, we have several ways to define a callback as follows:

As we now know how to define and use handlers, let's review some real life examples as follows:

Now, let's look at another example. In Yii, you can translate strings to different languages using Yii::t. As we all love perfect projects all language translations should be up to date. If they are not, we would like to receive an e-mail about it.

Events come in handy again here. In particular, the CMessageSource::onMissingTranslation event that is called when the translation for a string passed to Yii::t is missing.

This time we will use the application configuration file protected/config/main.php to attach an event handler as follows:

…
'components' => array(
    …
    // messages component class is CPhpMessageSource by default
    'messages' => array(
        // using static class method as event handler
        'onMissingTranslation' => array('MyEventHandler', 'handleMissingTranslation'),
    ),
    …
)
…

Now, we should implement our handler. Create protected/components/MyEventHandler.php as follows:

class MyEventHandler
{
    static function handleMissingTranslation($event)
    {
        // event class for this event is CMissingTranslationEvent    
        // so we can get some info about the message
        $text = implode("\n", array(
           'Language: '.$event->language,
           'Category:'.$event->category,
           'Message:'.$event->message         
        ));
        // sending email
		mail('admin@example.com', 'Missing translation', $text);
    }
}

Let's look at the last example. We have a blog application and we need to send an e-mail when there is a new comment (Comment) to the blog post (Post).

Comment is a standard AR model generated with Gii. Post is the same Gii-generated model except some customized methods. We will need a custom event NewCommentEvent to store both Post and Comment models and a handler class Notifier that will do the work.

It is not always necessary to attach an event handler. Let's look at how we can handle an event that is already declared inside an existing component by overriding a base class method. For example, we have a form model UserForm used to collect some information about our application user and we need to get the complete name from the first and the last name entered by the user.

Fortunately, in CModel, which is a base class for all Yii models including form models, CModel::afterValidate method is defined. This method is being called after a successful form validation. Let's use it in our protected/models/UserForm.php model:

class UserForm extends CFormModel
{
    public $firstName;
    public $lastName;
    public $fullName;

    public function rules()
    {
        return array(
            // First name and last name are required
            array('firstName, lastName', 'required'),
        );
    }

    // $event argument here is CEvent instance that
    // was created passed when an event method was called.
    // This time it was happened inside of
    // CModel::afterValidate().
    function afterValidate()
    {
        // If this method was called then
        // the model is already filled
        // with data and data is valid
        // so we can use it safely:
        $this->fullName = $this->firstName.' '.$this->lastName;

        // It's important to call parent class method
        // so all other event handlers are called
        return parent::afterValidate();
    }
}

We need to call parent method inside of afterValidate because parent implementation calls onAfterValidate that actually raises events:

protected function afterValidate()
{
   $this->onAfterValidate(new CEvent($this));
}

The approach described above can be used to customize your Active Record models and implement your own model behaviors.

Let's look at application.apis.lyrics.LyricsFinder:

application is a standard alias that points to your application protected folder and is translated into a filesystem path. The following table shows some more standard aliases:

apis.lyrics are translated to apis/lyrics and are appended to a path retrieved from the application alias, and LyricsFinder is the class name we want to import.

If LyricsFinder requires some additional classes located in its directory, then we can use Yii::import('application.apis.lyrics.*') to import the whole directory. Note that * does not include subfolders, so if you need lyrics/includes, you should add another import statement Yii::import('application.apis.lyrics.includes.*').

For performance reasons, it is better to use explicit paths with a class name instead of * if you are importing a single class.

If you want your classes to be imported automatically like the Yii core classes, then you can configure global imports in your main.php configuration file:

return array(
   // …

   // global imports
   'import'=>array(
      'application.models.*',
       'application.components.*',
       'application.apis.lyrics.*',
      'application.apis.lyrics.includes.*',
      'application.apis.albums.AlbumFinder',
   ),

Yii converts all non-fatal application errors to CException automatically.

Additionally, the default exception handler raises either the onError or an onException event. The default event handler writes a log message with error level set to error. Additionally, if your application's YII_DEBUG constant is set to true, unhandled exception or error will be displayed at a handy error screen. This screen includes a call stack trace, a code area where the exception was raised, and the file and line where you can look for the code to fix.

For further information, refer to the following URLs:

If you have worked with Yii before, then you have probably configured a database connection:

return array(
   …
   'components'=>array(
      'db'=>array(
         'class'=>'system.db.CDbConnection',
         'connectionString'=>'mysql:host=localhost;dbname=database_name',
         'username'=>'root',
         'password'=>'',
         'charset'=>'utf8',
      ),
      …
   ),
   …
);

This way of configuring component is used when you want to use a component across all application parts. With the preceding configuration, you can access a component by its name, such as Yii::app()->db.

When you are using the Yii::app()->db component for the first time directly or through active record model, Yii creates a component and initializes its public properties with the corresponding values provided in db array under the components section of the main.php application configuration file. In the preceding code, 'connectionString' the value will be assigned to CDbConnection::connectionString, 'username' will be assigned to CDbConnection::username, and so on.

If you want to find out what 'charset' stands for or want to know what else you can configure in the db component, then you need to know its class. In case of db component, the class is CDbConnection. You can refer to its API page at http://www.yiiframework.com/doc/api/CDbConnection/ and look for its public properties you can set from config.

In the preceding code, the 'class' property is a bit special because it is used to specify component class name. It does not exist in the CDbConnection class. Therefore, it can be used to override a class as follows:

return array(
   …
   'components'=>array(
      'db'=>array(
         'class'=>'application.components.MyDbConnection',
         …
      ),
      …
   ),
   …
);

This way, you can override each application component and it is very useful whenever a standard component does not fit your application.

Now, let's find out which standard Yii application components you can configure. There are two application types bundled with Yii which are as follows:

Both are extended from CApplication, so both console and web applications are sharing its components.

You can get the component names from API pages (http://www.yiiframework.com/doc/api/) and the source code of the registerCoreComponents application method, but let's list them here so the list can be used as a reference.

Both console and web application components are listed in the following table:

Additional components available only for web application are listed in the following table:

You can add your own application components (classes extended from CComponent) by simply adding new configuration items and pointing their class properties to your custom classes.

A Yii web application provides a bunch of components. One of them is a widget factory that since Yii 1.1.3 can be used to set widget defaults.

This works much like the CSS cascade. You are setting the default overall style in an external file, but are still able to override this through inline styles for individual widgets.

All collections implement SPL IteratorAggregate, Traversable, and Countable. Lists and maps also implement SPL ArrayAccess. It allows using collections like a standard PHP construct. The following is a snippet from the CList API:

You can access the request component in your web application by using Yii::app()->getRequest(). So, let's review the most useful methods and their usage, methods that return different parts of the current URL. In the following table, returned parts are marked with a bold font.

The methods that allow us to ensure request type are getIsPostRequest, getIsAjaxRequest , and getRequestType.

If you are working with a lot of cookie values and want to shorten the code provided, then you can use a helper as follows:

class Cookie
{
  public static function get($name)
  {
       $cookie=Yii::app()->request->cookies[$name];
       if(!$cookie)
           return null;

       return $cookie->value;
  }

  public static function set($name, $value, $expiration=0)
  {
       $cookie=new CHttpCookie($name,$value);
       $cookie->expire = $expiration;
       Yii::app()->request->cookies[$name]=$cookie;
  }
}

After you drop this code into protected/components/Cookie.php, you will be able to perform the following:

class TestController extends CController
{
   public function actionIndex()
   {
      $cookie = Cookie::get('test');
      if($cookie)
         echo $cookie;      
      else
         Cookie::set('test','I am a cookie!!');
   }
}