Path Alias and Namespace

Yii uses path aliases extensively. A path alias is associated with a directory or file path. It is specified in dot syntax, similar to that of widely adopted namespace format:


where RootAlias is the alias of some existing directory. By calling YiiBase::setPathOfAlias(), we can define new path aliases.For convenience, Yii predefines the following root aliases:

  • system: refers to the Yii framework directory;
  • application: refers to the application's base directory;
  • webroot: refers to the directory containing the entry script file. This alias has been available since version 1.0.3.
  • ext: refers to the directory containing all third-party extensions. This alias has been available since version 1.0.8.

Additionally, if the application uses modules, a root alias is also predefined for each module ID and refers to the base path of the corresponding module. This feature has been available since version 1.0.3.

By using YiiBase::getPathOfAlias(), an alias can be translated to its corresponding path. For example, system.web.CController would be translated as yii/framework/web/CController.

Using aliases, it is very convenient to import the definition of a class. For example, if we want to include the definition of the CController class, we can call the following:


The import method differs from include and require in that it is more efficient. The class definition being imported is actually not included until it is referenced for the first time. Importing the same namespace multiple times is also much faster than include_once and require_once.

Tip: When referring to a class defined by the Yii framework, we do not need to import or include it. All core Yii classes are pre-imported.

We can also use the following syntax to import a whole directory so that the class files under the directory can be automatically included when needed.


Besides import, aliases are also used in many other places to refer to classes. For example, an alias can be passed to Yii::createComponent() to create an instance of the corresponding class, even if the class file was not included previously.

Do not confuse path alias with namespace. A namespace refers to a logical grouping of some class names so that they can be differentiated from other class names even if their names are the same, while path alias is used to refer to a class file or directory. Path alias does not conflict with namespace.

Tip: Because PHP prior to 5.3.0 does not support namespace intrinsically, you cannot create instances of two classes who have the same name but with different definitions. For this reason, all Yii framework classes are prefixed with a letter 'C' (meaning 'class') so that they can be differentiated from user-defined classes. It is recommended that the prefix 'C' be reserved for Yii framework use only, and user-defined classes be prefixed with other letters.