concept-autoloading.md 4.97 KB
Newer Older
Qiang Xue committed
1 2
Class Autoloading
=================
Qiang Xue committed
3

Qiang Xue committed
4
Yii relies on the [class autoloading mechanism](http://www.php.net/manual/en/language.oop5.autoload.php)
5
to locate and include all required class files. It provides a high-performance class autoloader that is compliant to the
Qiang Xue committed
6
[PSR-4 standard](https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md).
7 8
The autoloader is installed when you include the `Yii.php` file.

9
> Note: For simplicity of description, in this section we will only talk about autoloading of classes. However, keep in
10 11 12
  mind that the content we are describing here applies to autoloading of interfaces and traits as well.


Qiang Xue committed
13
Using the Yii Autoloader <a name="using-yii-autoloader"></a>
14 15 16 17
------------------------

To make use of the Yii class autoloader, you should follow two simple rules when creating and naming your classes:

18
* Each class must be under a namespace (e.g. `foo\bar\MyClass`)
19 20 21 22 23 24
* Each class must be saved in an individual file whose path is determined by the following algorithm:

```php
// $className is a fully qualified class name with the leading backslash
$classFile = Yii::getAlias('@' . str_replace('\\', '/', $className) . '.php');
```
Qiang Xue committed
25

26 27
For example, if a class name and namespace is `foo\bar\MyClass`, the [alias](concept-aliases.md) for the corresponding class file path
would be `@foo/bar/MyClass.php`. In order for this alias to be resolvable into a file path,
28
either `@foo` or `@foo/bar` must be a [root alias](concept-aliases.md#defining-aliases).
Qiang Xue committed
29

30
When using the [Basic Application Template](start-basic.md), you may put your classes under the top-level
31 32
namespace `app` so that they can be autoloaded by Yii without the need of defining a new alias. This is because
`@app` is a [predefined alias](concept-aliases.md#predefined-aliases), and a class name like `app\components\MyClass`
33
can be resolved into the class file `AppBasePath/components/MyClass.php`, according to the algorithm just described.
Qiang Xue committed
34

35
In the [Advanced Application Template](tutorial-advanced-app.md), each tier has its own root alias. For example,
36 37
the front-end tier has a root alias `@frontend`, while the back-end tier `@backend`. As a result, you may
put the front-end classes under the namespace `frontend` while the back-end classes are under `backend`. This will
38
allow these classes to be autoloaded by the Yii autoloader.
Qiang Xue committed
39

Qiang Xue committed
40

Qiang Xue committed
41
Class Map <a name="class-map"></a>
42
---------
Qiang Xue committed
43

44
The Yii class autoloader supports the *class map* feature, which maps class names to the corresponding class file paths.
45 46
When the autoloader is loading a class, it will first check if the class is found in the map. If so, the corresponding
file path will be included directly without further check. This makes class autoloading super fast. In fact,
47
all core Yii classes are autoloaded this way.
Qiang Xue committed
48

49
You may add a class to the class map, stored in `Yii::$classMap`, using:
Qiang Xue committed
50 51

```php
52
Yii::$classMap['foo\bar\MyClass'] = 'path/to/MyClass.php';
Qiang Xue committed
53 54
```

55 56 57 58
[Aliases](concept-aliases.md) can be used to specify class file paths. You should set the class map in the
[bootstrapping](runtime-bootstrapping.md) process so that the map is ready before your classes are used.


Qiang Xue committed
59
Using Other Autoloaders <a name="using-other-autoloaders"></a>
60 61
-----------------------

Qiang Xue committed
62
Because Yii embraces Composer as a package dependency manager, it is recommended that you also install
63 64
the Composer autoloader. If you are using 3rd-party libraries that have their own autoloaders, you should
also install those.
Qiang Xue committed
65

66 67
When using the Yii autoloader together with other autoloaders, you should include the `Yii.php` file
*after* all other autoloaders are installed. This will make the Yii autoloader the first one responding to
Qiang Xue committed
68
any class autoloading request. For example, the following code is extracted from
69
the [entry script](structure-entry-scripts.md) of the [Basic Application Template](start-basic.md). The first
70
line installs the Composer autoloader, while the second line installs the Yii autoloader:
71 72 73 74 75 76

```php
require(__DIR__ . '/../vendor/autoload.php');
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
```

Qiang Xue committed
77
You may use the Composer autoloader alone without the Yii autoloader. However, by doing so, the performance
78 79 80 81 82
of your class autoloading may be degraded, and you must follow the rules set by Composer in order for your classes
to be autoloadable.

> Info: If you do not want to use the Yii autoloader, you must create your own version of the `Yii.php` file
  and include it in your [entry script](structure-entry-scripts.md).
Qiang Xue committed
83 84


Qiang Xue committed
85
Autoloading Extension Classes <a name="autoloading-extension-classes"></a>
Qiang Xue committed
86 87 88 89 90 91 92
-----------------------------

The Yii autoloader is capable of autoloading [extension](structure-extensions.md) classes. The sole requirement
is that an extension specifies the `autoload` section correctly in its `composer.json` file. Please refer to the
[Composer documentation](https://getcomposer.org/doc/04-schema.md#autoload) for more details about specifying `autoload`.

In case you do not use the Yii autoloader, the Composer autoloader can still autoload extension classes for you.