|
|
|
Extensions
|
|
|
|
==========
|
|
|
|
|
|
|
|
> Note: This section is under development.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
> 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".
|
|
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
> 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.
|
|
|
|
|
|
|
|
Extensions installed by Composer are stored under the `BasePath/vendor` directory, where `BasePath` refers to the
|
|
|
|
application's [base path](structure-applications.md#basePath).
|
|
|
|
|
|
|
|
For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following:
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
// ...
|
|
|
|
|
|
|
|
"require": {
|
|
|
|
// ... other dependencies
|
|
|
|
|
|
|
|
"yiisoft/yii2-imagine": "*"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
> 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.
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
```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]);
|
|
|
|
```
|
|
|
|
|
|
|
|
> 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
|
|
|
|
|
|
|
|
|
|
|
|
## Creating Extensions
|
|
|
|
|
|
|
|
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',
|
|
|
|
],
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Core Extensions
|
|
|
|
|
|
|
|
|
|
|
|
## Best Practices
|
|
|
|
|