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

> Note: This section is under development.

Qiang Xue committed
6 7 8 9 10
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
11

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


Qiang Xue committed
16 17 18 19 20 21 22
## Using Extensions

To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/)
packages, and you can take the following two simple steps to install such an extension:

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

Qiang Xue committed
24 25
You may need to install [Composer](https://getcomposer.org/) if you do not have it. Composer is a dependency
manager. This means when installing a package, it will install all its dependent packages automatically.
Qiang Xue committed
26

Qiang Xue committed
27 28 29 30
> Info: By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository
  for open source Composer packages. You may also [create your own repository](https://getcomposer.org/doc/05-repositories.md#repository)
  and configure Composer to use it. This is useful if you are developing closed open extensions and want to share
  within your projects.
Qiang Xue committed
31

Qiang Xue committed
32 33
Extensions installed by Composer are stored under the `BasePath/vendor` directory, where `BasePath` refers to the
application's [base path](structure-applications.md#basePath).
Qiang Xue committed
34

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

```json
{
    // ...

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

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

Qiang Xue committed
49 50
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
51

Qiang Xue committed
52 53 54
> 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
55

Qiang Xue committed
56 57
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
58 59 60 61 62 63 64 65 66 67

```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
68 69 70 71 72 73
> Info: Extension classes are autoloaded using the [Yii class autoloader](concept-autoloading.md). Yii automatically
  creates [aliases](concept-aliases.md#extension-aliases) for the root namespaces declared by the extensions.

Also make sure in the [application configuration](structure-applications.md#application-configurations), you have
configured `extension

Qiang Xue committed
74 75 76

## Creating Extensions

Qiang Xue committed
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
You may consider creating an extension when you feel the need to redistribute some of your great code so that
they can be easily reused by other people or in your other projects.

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 so that it can be more easily
used elsewhere, liked described in the last subsection. Below are the steps you may follow to create an extension.

1. Put all the files you plan to include in the extension in a single directory. The directory should contain
   no other irrelevant files. For simplicity, let's call this directory the extension's *root directory*.
2. Create a `composer.json` file directly under the root directory. The file is required by Composer, which describes
   the metadata about your extension. Please refer to the [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup)
   for more details about the file format.
3. Create a VCS (version control system) repository to host the extension files. Any future development
   and maintenance work about the extension should be done on this repository.
4. Register your extension with a Composer repository so that other users can find and install your extension.
   If you are creating an open source extension, you can register it with [Packagist](https://packagist.org/);
   If you are creating a private extension for internal use, you may register it with
   [your own repository](https://getcomposer.org/doc/05-repositories.md#hosting-your-own).

As an example, you may refer to the [yiisoft/yii2-bootstrap](widget-bootstrap) extension which provides a set of
widgets encapsulating the Twitter Bootstrap plugins. The extension is hosted on [GitHub](https://github.com/yiisoft/yii2-bootstrap)
and registered with [Packagist](https://packagist.org/packages/yiisoft/yii2-bootstrap). Below is the content
of its `composer.json` file (some unimportant content is removed for simplicity):

```json
{
    "name": "yiisoft/yii2-bootstrap",
    "description": "The Twitter Bootstrap extension for the Yii framework",
    "keywords": ["yii2", "bootstrap"],
    "type": "yii2-extension",
    "license": "BSD-3-Clause",
    "require": {
        "yiisoft/yii2": "*",
        "twbs/bootstrap": "3.1.* | 3.0.*"
    },
    "autoload": {
        "psr-4": {
            "yii\\bootstrap\\": ""
        }
    }
}
```


### Yii2 Extensions

When creating a Composer package, you may specify the package type to be `yii2-extension`, like shown in the example
in the last subsection. This is recommended if your package is an extension that is specifically designed to be
used in Yii applications. By using `yii2-extension` as the package type, your package can get the following extra benefits:


For example, if your package contains a Yii [widget](structure-widgets.md), it is most likely
that the package


## Installing Extensions Manually

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

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.

If an extension does not have a class autoloader but follows the
[PSR-4 standard](https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md),
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
158 159
## Core Extensions

Qiang Xue committed
160 161 162

## Best Practices