Configuring components

Yii is a very customizable framework. Moreover, as in every customizable code, there should be a convenient way to set up different application parts. So in Yii, this is provided through a configuration file named main.php located at protected/config/.

How to do it…

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 a 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.

How it works…

When you are using the Yii::app()->db component for the first time directly or through the Active Record model, Yii creates a component and initializes its public properties with the corresponding values provided in the db array under the components section of the main.php application configuration file. In the preceding code, the 'connectionString' value will be assigned to CDbConnection::connectionString, the 'username' value 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 the 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 that you can set from config.

In the preceding code, the 'class' property is a bit special because it is used to specify the component's 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's component and it is very useful whenever a standard component does not fit your application.

There's more...

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:

• Web application (CWebApplication)

• Console application (CConsoleApplication)

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 that it can be used as a reference.

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

Component name	Default/suggested component class	Description
coreMessages	CPhpMessageSource	This component provides the source for translating Yii framework messages.
db	CDbConnection	This component provides a database connection.
messages	CPhpMessageSource	This component provides the source for translating application messages.
errorHandler	CErrorHandler	This component handles PHP errors and uncaught exceptions.
securityManager	CSecurityManager	This component provides security-related services, such as hashing, encryption, and so on.
statePersister	CStatePersister	This component provides global state persistence methods.
format	CFormatter	This component provides a set of commonly used data formatting methods.
cache	CFileCache	This component provides a caching feature.

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

Component name	Default component class	Description
session	CHttpSession	This component provides the session-related functionalities.
request	CHttpRequest	This component encapsulates the $_SERVER variable and resolves its inconsistency among different web servers. It also manages the cookies sent from and to the user.
urlManager	CUrlManager	URL router; used for both generating and resolving application URLs.
assetManager	CAssetManager	This component manages the publishing of private asset files.
user	CWebUser	This component represents the user's session information.
themeManager	CThemeManager	This component manages themes.
authManager	CPhpAuthManager	This component manages role-based access control (RBAC).
clientScript	CClientScript	This component manages client scripts (JavaScript and CSS).
widgetFactory	CWidgetFactory	This component creates widgets and supports widget skinning.

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.