structure-extensions.md 21.4 KB
Newer Older
Qiang Xue committed
1 2 3
Extensions
==========

Qiang Xue committed
4 5 6 7 8
Extensions are redistributable software packages specifically designed to be used in Yii applications and provide
ready-to-use features. For example, the [yiisoft/yii2-debug](tool-debugger.md) extension adds a handy debug toolbar
at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can
use extensions to accelerate your development process. You can also package your code as extensions to share with
other people your great work.
Qiang Xue committed
9

Qiang Xue committed
10
> Info: We use the term "extension" to refer to Yii-specific software packages. For general purpose software packages
Qiang Xue committed
11
  that can be used without Yii, we will refer to them using the term "package" or "library".
Qiang Xue committed
12 13


14
## Using Extensions <a name="using-extensions"></a>
Qiang Xue committed
15 16

To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/)
Qiang Xue committed
17
packages which can be installed by taking the following two simple steps:
Qiang Xue committed
18 19

1. modify the `composer.json` file of your application and specify which extensions (Composer packages) you want to install.
20
2. run `composer install` to install the specified extensions.
Qiang Xue committed
21

22
Note that you may need to install [Composer](https://getcomposer.org/) if you do not have it.
Qiang Xue committed
23

Qiang Xue committed
24 25 26
By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository
for open source Composer packages. You can look for extensions on Packagist. You may also
[create your own repository](https://getcomposer.org/doc/05-repositories.md#repository) and configure Composer
Alexander Makarov committed
27
to use it. This is useful if you are developing private extensions that you want to share within your projects only.
Qiang Xue committed
28

Qiang Xue committed
29
Extensions installed by Composer are stored in the `BasePath/vendor` directory, where `BasePath` refers to the
30 31
application's [base path](structure-applications.md#basePath).  Because Composer is a dependency manager, when
it installs a package, it will also install all its dependent packages.
Qiang Xue committed
32

Qiang Xue committed
33
For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following:
Qiang Xue committed
34 35 36 37 38 39 40 41 42 43 44 45 46

```json
{
    // ...

    "require": {
        // ... other dependencies

        "yiisoft/yii2-imagine": "*"
    }
}
```

Qiang Xue committed
47 48
After the installation, you should see the directory `yiisoft/yii2-imagine` under `BasePath/vendor`. You should
also see another directory `imagine/imagine` which contains the installed dependent package.
Qiang Xue committed
49

Qiang Xue committed
50 51 52
> Info: The `yiisoft/yii2-imagine` is a core extension developed and maintained by the Yii developer team. All
  core extensions are hosted on [Packagist](https://packagist.org/) and named like `yiisoft/yii2-xyz`, where `xyz`
  varies for different extensions.
Qiang Xue committed
53

Qiang Xue committed
54 55
Now you can use the installed extensions like they are part of your application. The following example shows
how you can use the `yii\imagine\Image` class provided by the `yiisoft/yii2-imagine` extension:
Qiang Xue committed
56 57 58 59 60 61 62 63 64 65

```php
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]);
```

Qiang Xue committed
66
> Info: Extension classes are autoloaded by the [Yii class autoloader](concept-autoloading.md).
Qiang Xue committed
67

Qiang Xue committed
68

69
### Installing Extensions Manually <a name="installing-extensions-manually"></a>
Qiang Xue committed
70

71
In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer.
72
To do so, you should:
Qiang Xue committed
73

74 75 76
1. download the extension archive files 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.
Qiang Xue committed
77

78 79 80 81 82 83 84 85 86 87 88 89 90
If an extension does not have a class autoloader but follows the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/),
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](concept-aliases.md#defining-aliases) for the extension root directory. For example,
assuming you have installed an extension in the directory `vendor/mycompany/myext`, and the extension classes
are under the `myext` namespace, then you can include the following code in your application configuration:

```php
[
    'aliases' => [
        '@myext' => '@vendor/mycompany/myext',
    ],
]
```
Qiang Xue committed
91 92


93
## Creating Extensions <a name="creating-extensions"></a>
Qiang Xue committed
94

95 96 97 98
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.

It is recommended that you create an extension in terms of a [Composer package](https://getcomposer.org/) so that
99
it can be more easily installed and used by other users, as described in the last subsection.
100 101

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

Qiang Xue committed
103
1. Create a project for your extension and host it on a VCS repository, such as [github.com](https://github.com).
104
   The development and maintenance work for the extension should be done on this repository.
Qiang Xue committed
105 106
2. Under the root directory of the project, create a file named `composer.json` as required by Composer. Please
   refer to the next subsection for more details.
107 108
3. Register your extension with a Composer repository, such as [Packagist](https://packagist.org/), so that
   other users can find and install your extension using Composer.
Qiang Xue committed
109

Qiang Xue committed
110

111
### `composer.json` <a name="composer-json"></a>
Qiang Xue committed
112 113 114

Each Composer package must have a `composer.json` file in its root directory. The file contains the metadata about
the package. You may find complete specification about this file in the [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup).
115
The following example shows the `composer.json` file for the `yiisoft/yii2-imagine` extension:
Qiang Xue committed
116 117 118

```json
{
Qiang Xue committed
119 120 121 122
    // package name
    "name": "yiisoft/yii2-imagine",

    // package type
Qiang Xue committed
123
    "type": "yii2-extension",
Qiang Xue committed
124 125 126

    "description": "The Imagine integration for the Yii framework",
    "keywords": ["yii2", "imagine", "image", "helper"],
Qiang Xue committed
127
    "license": "BSD-3-Clause",
Qiang Xue committed
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
    "support": {
        "issues": "https://github.com/yiisoft/yii2/issues?labels=ext%3Aimagine",
        "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",
            "email": "amigo.cobos@gmail.com"
        }
    ],

    // package dependencies
Qiang Xue committed
143 144
    "require": {
        "yiisoft/yii2": "*",
Qiang Xue committed
145
        "imagine/imagine": "v0.5.0"
Qiang Xue committed
146
    },
Qiang Xue committed
147 148

    // class autoloading specs
Qiang Xue committed
149 150
    "autoload": {
        "psr-4": {
Qiang Xue committed
151
            "yii\\imagine\\": ""
Qiang Xue committed
152 153 154 155 156
        }
    }
}
```

Qiang Xue committed
157

158
#### Package Name <a name="package-name"></a>
Qiang Xue committed
159

160 161 162
Each Composer package should have a package name which uniquely identifies the package among all others.
The format of package names is `vendorName/projectName`. For example, in the package name `yiisoft/yii2-imagine`,
the vendor name and the project name are `yiisoft` and `yii2-imagine`, respectively.
Qiang Xue committed
163

164
Do NOT use `yiisoft` as your vendor name as it is reserved for use by the Yii core code.
Qiang Xue committed
165

166 167
We recommend you prefix `yii2-` to the project name for packages representing Yii 2 extensions, for example,
`myname/yii2-mywidget`. This will allow users to more easily tell whether a package is a Yii 2 extension.
Qiang Xue committed
168 169


170
#### Package Type <a name="package-type"></a>
Qiang Xue committed
171

172 173
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.
Qiang Xue committed
174

175
When a user runs `composer install` to install an extension, the file `vendor/yiisoft/extensions.php`
176
will be automatically updated to include the information about the new extension. From this file, Yii applications
177
can know which extensions are installed (the information can be accessed via [[yii\base\Application::extensions]]).
Qiang Xue committed
178

Qiang Xue committed
179

180
#### Dependencies <a name="dependencies"></a>
Qiang Xue committed
181

Qiang Xue committed
182
Your extension depends on Yii (of course). So you should list it (`yiisoft/yii2`) in the `require` entry in `composer.json`.
183
If your extension also depends on other extensions or third-party libraries, you should list them as well.
Qiang Xue committed
184
Make sure you also list appropriate version constraints (e.g. `1.*`, `@stable`) for each dependent package. Use stable
185
dependencies when your extension is released in a stable version.
Qiang Xue committed
186

Qiang Xue committed
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208
Most JavaScript/CSS packages are managed using [Bower](http://bower.io/) and/or [NPM](https://www.npmjs.org/),
instead of Composer. Yii uses the [Composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin)
to enable managing these kinds of packages through Composer. If your extension depends on a Bower package, you can
simply list the dependency in `composer.json` like the following:

```json
{
    // package dependencies
    "require": {
        "bower-asset/jquery": ">=1.11.*"
    }
}
```

The above code states that the extension depends on the `jquery` Bower package. In general, you can use
`bower-asset/PackageName` to refer to a Bower package in `composer.json`, and use `npm-asset/PackageName`
to 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/Packages` directories, 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](structure-assets.md#bower-npm-assets) section.

209 210

#### Class Autoloading <a name="class-autoloading"></a>
Qiang Xue committed
211 212 213 214 215 216 217

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 the `composer.json` file, like shown below:

```json
{
    // ....
Qiang Xue committed
218

Qiang Xue committed
219 220 221 222 223 224 225 226 227 228
    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}
```

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

229 230
When the extension is installed in an application, Yii will create for each listed root namespace
an [alias](concept-aliases.md#extension-aliases) that refers to the directory corresponding to the namespace.
Qiang Xue committed
231 232 233
For example, the above `autoload` declaration will correspond to an alias named `@yii/imagine`.


234 235
### Recommended Practices <a name="recommended-practices"></a>

236
Because extensions are meant to be used by other people, you often need to make an extra effort during development. Below
237 238 239 240 241 242 243 244 245
we introduce some common and recommended practices in creating high quality extensions.


#### Namespaces <a name="namespaces"></a>

To avoid name collisions and make the classes in your extension autoloadable, you should use namespaces and
name the classes in your extension by following the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/) or
[PSR-0 standard](http://www.php-fig.org/psr/psr-0/).

246
Your class namespaces should start with `vendorName\extensionName`, where `extensionName` is similar to the project name
247
in the package name except that it should not contain the `yii2-` prefix. For example, for the `yiisoft/yii2-imagine`
248
extension, we use `yii\imagine` as the namespace for its classes.
249

250
Do not use `yii`, `yii2` or `yiisoft` as your vendor name. These names are reserved for use by the Yii core code.
251 252 253


#### Bootstrapping Classes <a name="bootstrapping-classes"></a>
Qiang Xue committed
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290

Sometimes, you may want your extension to execute some code during the [bootstrapping process](runtime-bootstrapping.md)
stage of an application. For example, your extension may want to respond to the application's `beginRequest` event
to adjust some environment settings. While you can instruct users of the extension to explicitly attach your event
handler in the extension to the `beginRequest` event, a better way is to do this automatically.

To achieve this goal, you can create a so-called *bootstrapping class* by implementing [[yii\base\BootstrapInterface]].
For example,

```php
namespace myname\mywidget;

use yii\base\BootstrapInterface;
use yii\base\Application;

class MyBootstrapClass implements BootstrapInterface
{
    public function bootstrap($app)
    {
        $app->on(Application::EVENT_BEFORE_REQUEST, function () {
             // do something here
        });
    }
}
```

You then list this class in the `composer.json` file of your extension like follows,

```json
{
    // ...

    "extra": {
        "bootstrap": "myname\\mywidget\\MyBootstrapClass"
    }
}
```
Qiang Xue committed
291

Qiang Xue committed
292
When the extension is installed in an application, Yii will automatically instantiate the bootstrapping class
293
and call its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method during the bootstrapping process for
Qiang Xue committed
294
every request.
Qiang Xue committed
295 296


297
#### Working with Databases <a name="working-with-databases"></a>
Qiang Xue committed
298

299 300 301 302
Your extension may need to access databases. Do not assume that the applications that use your extension will always
use `Yii::$db` as the DB connection. Instead, you should declare a `db` property for the classes that require DB access.
The property will allow users of your extension to customize which DB connection they would like your extension to use.
As an example, you may refer to the [[yii\caching\DbCache]] class and see how it declares and uses the `db` property.
Qiang Xue committed
303

304
If your extension needs to create specific DB tables or make changes to DB schema, you should
Qiang Xue committed
305

306 307 308
- provide [migrations](db-migrations.md) to manipulate DB schema, rather than using plain SQL files;
- try to make the migrations applicable to different DBMS;
- avoid using [Active Record](db-active-record.md) in the migrations.
Qiang Xue committed
309 310


311 312 313 314 315 316 317 318 319 320 321 322
#### Using Assets <a name="using-assets"></a>

If your extension is a widget or a module, chances are that it may require some [assets](structure-assets.md) to work.
For example, a module may display some pages which contain images, JavaScript, and CSS. Because the files of an
extension are all under the same directory which is not Web accessible when installed in an application, you have
two choices to make the asset files directly accessible via Web:

- ask users of the extension to manually copy the asset files to a specific Web-accessible folder;
- declare an [asset bundle](structure-assets.md) and rely on the asset publishing mechanism to automatically
  copy the files listed in the asset bundle to a Web-accessible folder.

We recommend you use the second approach so that your extension can be more easily used by other people.
Andrei Chugunov committed
323
Please refer to the [Assets](structure-assets.md) section for more details about how to work with assets in general.
Qiang Xue committed
324

Qiang Xue committed
325

Qiang Xue committed
326
#### Internationalization and Localization <a name="i18n-l10n"></a>
Qiang Xue committed
327

328 329
Your extension may be used by applications supporting different languages! Therefore, if your extension displays
content to end users, you should try to [internationalize and localize](tutorial-i18n.md) it. In particular,
Qiang Xue committed
330

331 332 333
- If the extension displays messages intended for end users, the messages should be wrapped into `Yii::t()`
  so that they can be translated. Messages meant for developers (such as internal exception messages) do not need
  to be translated.
334
- If the extension displays numbers, dates, etc., they should be formatted using [[yii\i18n\Formatter]] with
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358
  appropriate formatting rules.

For more details, please refer to the [Internationalization](tutorial-i18n.md) section.


#### Testing <a name="testing"></a>

You want your extension to run flawlessly without bringing problems to other people. To reach this goal, you should
test your extension before releasing it to public.

It is recommended that you create various test cases to cover your extension code rather than relying on manual tests.
Each time before you release a new version of your extension, you may simply run these test cases to make sure
everything is in good shape. Yii provides testing support, which can help you to more easily write unit tests,
acceptance tests and functionality tests. For more details, please refer to the [Testing](test-overview.md) section.


#### Versioning <a name="versioning"></a>

You should give each release of your extension a version number (e.g. `1.0.1`). We recommend you follow the
[semantic versioning](http://semver.org) practice when determining what version numbers should be used.


#### Releasing <a name="releasing"></a>

359
To let other people know about your extension, you need to release it to the public.
360

361 362
If it is the first time you are releasing an extension, you should register it on a Composer repository, such as
[Packagist](https://packagist.org/). After that, all you need to do is simply create a release tag (e.g. `v1.0.1`)
363 364 365
on the VCS repository of your extension and notify the Composer repository about the new release. People will
then be able to find the new release, and install or update the extension through the Composer repository.

366
In the releases of your extension, in addition to code files, you should also consider including the following to
367 368 369 370 371 372 373 374 375 376 377
help other people learn about and use your extension:

* A readme file in the package root directory: it describes what your extension does and how to install and use it.
  We recommend you write it in [Markdown](http://daringfireball.net/projects/markdown/) format and name the file
  as `readme.md`.
* A changelog file in the package root directory: it lists what changes are made in each release. The file
  may be written in Markdown format and named as `changelog.md`.
* An upgrade file in the package root directory: it gives the instructions on how to upgrade from older releases
  of the extension. The file may be written in Markdown format and named as `upgrade.md`.
* Tutorials, demos, screenshots, etc.: these are needed if your extension provides many features that cannot be
  fully covered in the readme file.
378
* API documentation: your code should be well documented to allow other people to more easily read and understand it.
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435
  You may refer to the [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php)
  to learn how to document your code.

> Info: Your code comments can be written in Markdown format. The `yiisoft/yii2-apidoc` extension provides a tool
  for you to generate pretty API documentation based on your code comments.

> Info: While not a requirement, we suggest your extension adhere to certain coding styles. You may refer to
  the [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style).


## Core Extensions <a name="core-extensions"></a>

Yii provides the following core extensions that are developed and maintained by the Yii developer team. They are all
registered on [Packagist](https://packagist.org/) and can be easily installed as described in the
[Using Extensions](#using-extensions) subsection.

- [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc):
  provides an extensible and high-performance API documentation generator. It is also used to generate the core
  framework API documentation.
- [yiisoft/yii2-authclient](https://github.com/yiisoft/yii2-authclient):
  provides a set of commonly used auth clients, such as Facebook OAuth2 client, GitHub OAuth2 client.
- [yiisoft/yii2-bootstrap](https://github.com/yiisoft/yii2-bootstrap):
  provides a set of widgets that encapsulate the [Bootstrap](http://getbootstrap.com/) components and plugins.
- [yiisoft/yii2-codeception](https://github.com/yiisoft/yii2-codeception):
  provides testing support based on [Codeception](http://codeception.com/).
- [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug):
  provides debugging support for Yii applications. When this extension is used, a debugger toolbar will appear
  at the bottom of every page. The extension also provides a set of standalone pages to display more detailed
  debug information.
- [yiisoft/yii2-elasticsearch](https://github.com/yiisoft/yii2-elasticsearch):
  provides the support for using [Elasticsearch](http://www.elasticsearch.org/). It includes basic querying/search
  support and also implements the [Active Record](db-active-record.md) pattern that allows you to store active records
  in Elasticsearch.
- [yiisoft/yii2-faker](https://github.com/yiisoft/yii2-faker):
  provides the support for using [Faker](https://github.com/fzaninotto/Faker) to generate fake data for you.
- [yiisoft/yii2-gii](https://github.com/yiisoft/yii2-gii):
  provides a Web-based code generator that is highly extensible and can be used to quickly generate models,
  forms, modules, CRUD, etc.
- [yiisoft/yii2-imagine](https://github.com/yiisoft/yii2-imagine):
  provides commonly used image manipulation functions based on [Imagine](http://imagine.readthedocs.org/).
- [yiisoft/yii2-jui](https://github.com/yiisoft/yii2-jui):
  provides a set of widgets that encapsulate the [JQuery UI](http://jqueryui.com/) interactions and widgets.
- [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb):
  provides the support for using [MongoDB](http://www.mongodb.org/). It includes features such as basic query,
  Active Record, migrations, caching, code generation, etc.
- [yiisoft/yii2-redis](https://github.com/yiisoft/yii2-redis):
  provides the support for using [redis](http://redis.io/). It includes features such as basic query,
  Active Record, caching, etc.
- [yiisoft/yii2-smarty](https://github.com/yiisoft/yii2-smarty):
  provides a template engine based on [Smarty](http://www.smarty.net/).
- [yiisoft/yii2-sphinx](https://github.com/yiisoft/yii2-sphinx):
  provides the support for using [Sphinx](http://sphinxsearch.com). It includes features such as basic query,
  Active Record, code generation, etc.
- [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer):
  provides email sending features based on [swiftmailer](http://swiftmailer.org/).
- [yiisoft/yii2-twig](https://github.com/yiisoft/yii2-twig):
  provides a template engine based on [Twig](http://twig.sensiolabs.org/).