EXTENSIONS 133 Now you can use the installed extensions like they are part of your

appli-cation. The following example shows how you can use theyii\imagine\Image

class provided by the yiisoft/yii2-imagineextension:

use Yii;

use yii\imagine\Image;

// generate a thumbnail image

Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)

->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' =>

50]);

Info: Extension classes are autoloaded by the Yii class autoloader.

Installing Extensions Manually

In some rare occasions, you may want to install some or all extensions man-ually, rather than relying on Composer. To do so, you should:

1. download the extension archive les and unpack them in the ^vendor directory.

2. install the class autoloaders provided by the extensions, if any.

3. download and install all dependent extensions as instructed.

If an extension does not have a class autoloader but follows the PSR-4 stan-dard⁴⁴, you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to declare a root alias for the extension root directory. For example, assuming you have installed an ex-tension in the directoryvendor/mycompany/myext, and the extension classes are under the^myextnamespace, then you can include the following code in your application conguration:

[ 'aliases' => [

'@myext' => '@vendor/mycompany/myext', ] ],

3.12.2 Creating Extensions

You may consider creating an extension when you feel the need to share with other people your great code. An extension can contain any code you like, such as a helper class, a widget, a module, etc.

44http://www.php-fig.org/psr/psr-4/

134 CHAPTER 3. APPLICATION STRUCTURE It is recommended that you create an extension in terms of a Composer package⁴⁵so that it can be more easily installed and used by other users, as described in the last subsection.

Below are the basic steps you may follow to create an extension as a Composer package.

1. Create a project for your extension and host it on a VCS repository, such as github.com⁴⁶. The development and maintenance work for the extension should be done on this repository.

2. Under the root directory of the project, create a le named ^composer.

jsonas required by Composer. Please refer to the next subsection for more details.

3. Register your extension with a Composer repository, such as Pack-agist⁴⁷, so that other users can nd and install your extension using Composer.

composer.json

Each Composer package must have acomposer.jsonle in its root directory.

The le contains the metadata about the package. You may nd complete specication about this le in the Composer Manual⁴⁸. The following exam-ple shows thecomposer.jsonle for theyiisoft/yii2-imagine extension:

{

// package name

"name": "yiisoft/yii2-imagine", // package type

"type": "yii2-extension",

"description": "The Imagine integration for the Yii framework",

"keywords": ["yii2", "imagine", "image", "helper"],

"license": "BSD-3-Clause",

"support": {

"issues": "https://github.com/yiisoft/yii2/issues?labels=ext%3 Aimagine",

"forum": "http://www.yiiframework.com/forum/",

"wiki": "http://www.yiiframework.com/wiki/",

"irc": "irc://irc.freenode.net/yii",

"source": "https://github.com/yiisoft/yii2"

},"authors": [

{ "name": "Antonio Ramirez",

45https://getcomposer.org/

46https://github.com

47https://packagist.org/

48https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup

3.12. EXTENSIONS 135

"email": "[email protected]"

], }

// package dependencies

"require": {

"yiisoft/yii2": "*",

"imagine/imagine": "v0.5.0"

},

// class autoloading specs

"autoload": {

"psr-4": {

"yii\\imagine\\": ""

} } }

Package Name Each Composer package should have a package name which uniquely identies the package among all others. The format of pack-age names is vendorName/projectName. For example, in the package name

yiisoft/yii2-imagine, the vendor name and the project name areyiisoft and

yii2-imagine, respectively.

Do NOT useyiisoft as your vendor name as it is reserved for use by the Yii core code.

We recommend you prex yii2-to the project name for packages repre-senting Yii 2 extensions, for example, myname/yii2-mywidget. This will allow users to more easily tell whether a package is a Yii 2 extension.

Package Type It is important that you specify the package type of your extension as yii2-extension so that the package can be recognized as a Yii extension when being installed.

When a user runscomposer installto install an extension, the le vendor /yiisoft/extensions.php will be automatically updated to include the infor-mation about the new extension. From this le, Yii applications can know which extensions are installed (the information can be accessed via yii\base

\Application::$extensions).

Dependencies Your extension depends on Yii (of course). So you should list it (yiisoft/yii2) in the require entry in composer.json. If your extension also depends on other extensions or third-party libraries, you should list them as well. Make sure you also list appropriate version constraints (e.g.

1.*,@stable) for each dependent package. Use stable dependencies when your extension is released in a stable version.

136 CHAPTER 3. APPLICATION STRUCTURE Most JavaScript/CSS packages are managed using Bower⁴⁹and/or NPM⁵⁰, instead of Composer. Yii uses the Composer asset plugin⁵¹ to enable man-aging these kinds of packages through Composer. If your extension depends on a Bower package, you can simply list the dependency incomposer.jsonlike the following:

{

// package dependencies

"require": {

"bower-asset/jquery": ">=1.11.*"

} }

The above code states that the extension depends on thejqueryBower pack-age. In general, you can usebower-asset/PackageNameto refer to a Bower pack-age incomposer.json, and usenpm-asset/PackageNameto refer to a NPM package.

When Composer installs a Bower or NPM package, by default the package content will be installed under the@vendor/bower/PackageName and@vendor/npm /Packagesdirectories, respectively. These two directories can also be referred to using the shorter aliases@bower/PackageName and@npm/PackageName.

For more details about asset management, please refer to the Assets section.

Class Autoloading In order for your classes to be autoloaded by the Yii class autoloader or the Composer class autoloader, you should specify the

autoload entry in thecomposer.jsonle, like shown below:

{ // ....

"autoload": {

"psr-4": {

"yii\\imagine\\": ""

} } }

You may list one or multiple root namespaces and their corresponding le paths.

When the extension is installed in an application, Yii will create for each listed root namespace an alias that refers to the directory corresponding to the namespace. For example, the aboveautoloaddeclaration will correspond to an alias named@yii/imagine.

49http://bower.io/

50https://www.npmjs.org/

51https://github.com/francoispluchino/composer-asset-plugin

3.12. EXTENSIONS 137