The Yii framework was designed to be easily extensible. Additional features can be added to your project and then reused, either by yourself on other projects or by sharing your work as a formal Yii extension.
Code style
----------
To be consistent with core Yii conventions, your extensions ought to adhere to certain coding styles:
- Use the [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style).
- Document classes, methods and properties using [phpdoc](http://www.phpdoc.org/). - Extension classes should *not* be prefixed. Do not use the format `TbNavBar`, `EMyWidget`, etc.
> Note that you can use Markdown within your code for documentation purposes. With Markdown, you can link to properties and methods using the following syntax: `[[name()]]`, `[[namespace\MyClass::name()]]`.
### Namespace
Yii 2 relies upon namespaces to organize code. (Namespace support was added to PHP in version 5.3.) If you want to use namespaces within your extension,
- Do not use `yiisoft` anywhere in your namespaces.
- Do not use `\yii`, `\yii2` or `\yiisoft` as root namespaces.
- Namespaces should use the syntax `vendorName\uniqueName`.
Choosing a unique namespace is important to prevent name collisions, and also results in faster autoloading of classes. Examples of unique, consistent namepacing are:
- `samdark\wiki`
- `samdark\debugger`
- `samdark\googlemap`
Distribution
------------
Beyond the code itself, the entire extension distribution ought to have certain things.
There should be a `readme.md` file, written in English. This file should clearly describe what the extension does, its requirements, how to install it,
and to use it. The README should be written using Markdown. If you want to provide translated README files, name them as `readme_ru.md`
where `ru` is your language code (in this case, Russian).
It is a good idea to include some screenshots as part of the documentation, especially if your extension provides a widget.
It is recommended to host your extensions at [Github](https://github.com).
Extensions should also be registered at [Packagist](https://packagist.org) in order to be installable via Composer.
### Composer package name
Choose your extension's package name wisely, as you shouldn't change the package name later on. (Changing the name leads to losing the Composer stats, and makes it impossible for people to install the package by the old name.)
If your extension was made specifically for Yii2 (i.e. cannot be used as a standalone PHP library) it is recommended to
name it like the following:
```
yii2-my-extension-name-type
```
Where:
- `yii2-` is a prefix.
- The extension name is in all lowercase letters, with words separated by `-`.
- The `-type` postfix may be `widget`, `behavior`, `module` etc.
### Dependencies
Some extensions you develop may have their own dependencies, such as relying upon other extensions or third-party libraries. When dependencies exist, you should require them in your extension's `composer.json` file. Be certain to also use appropriate version constraints, eg. `1.*`, `@stable` for requirements.
Finally, when your extension is released in a stable version, double-check that its requirements do not include `dev` packages that do not have a `stable` release. In other words, the stable release of your extension should only rely upon stable dependencies.
### Versioning
As you maintain and upgrading your extension,
- Use the rules of [semantic versioning](http://semver.org).
- Use a consistent format for your repository tags, as they are treated as version strings by composer, eg. `0.2.4`,
`0.2.5`,`0.3.0`,`1.0.0`.
### composer.json
Yii2 uses Composer for installation, and extensions for Yii2 should as well. Towards that end,
- Use the type `yii2-extension` in `composer.json` file if your extension is Yii-specific.
- Do not use `yii` or `yii2` as the Composer vendor name.
- Do not use `yiisoft` in the Composer package name or the Composer vendor name.
If your extension classes reside directly in the repository root directory, you can use the PSR-4 autoloader in the following way in your `composer.json` file:
```json
{
"name": "myname/mywidget",
"description": "My widget is a cool widget that does everything",
All of the details can be found in the guide, but you'll either download Composer directly from <http://getcomposer.org/>, or run the following command:
```
curl -s http://getcomposer.org/installer | php
```
We strongly recommend a global composer installation.
Installing Composer Class Autoloader
------------------------------------
Make sure the [entry script](concept-entry-scripts.md) of your application contains the following lines of code:
The act of [installing a Yii application](installation.md) with
```
composer.phar create-project --stability dev yiisoft/yii2-app-basic
```
creates a new root directory for your project along with the `composer.json` and `compoer.lock` file.
While the former lists the packages, which your application requires directly together with a version constraint, while the latter keeps track of all installed packages and their dependencies in a specific revision. Therefore the `composer.lock` file should also be [committed to your version control system](https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file).
These two files are strongly linked to the two composer commands `update` and `install`.
Usually, when working with your project, such as creating another copy for development or deployment, you will use
```
composer.phar install
```
to make sure you get exactly the same packages and versions as specified in `composer.lock`.
Only if want to intentionally update the packages in your project you should run
```
composer.phar update
```
As an example, packages on `dev-master` will constantly get new updates when you run `update`, while running `install` won't, unless you've pulled an update of the `composer.lock` file.
There are several parameters available to the above commands. Very commonly used ones are `--no-dev`, which would skip packages in the `require-dev` section and `--prefer-dist`, which downloads archives if available, instead of checking out repositories to your `vendor` folder.
> Composer commands must be executed within your Yii project's directory, where the `composer.json` file can be found.
Depending upon your operating system and setup, you may need to provide paths to the PHP executable and
to the `composer.phar` script.
Adding more packages to your project
------------------------------------
To add two new packages to your project run the follwing command:
This will resolve the dependencies and then update your `composer.json` file.
The above example says that a version greater than or equal to 1.0.3 of indent converter package
and version 1.1 or greater of gravatar extension are required.
For details of this syntax, see the [official Composer documentation](https://getcomposer.org/doc/01-basic-usage.md#package-versions).
The full list of available Composer-supported PHP packages can be found at [packagist](http://packagist.org/). You may also search packages interactively just by entering `composer.phar require`.
### Manually editing your version constraints
You may also edit the `composer.json` file manually. Within the `require` section, you specify the name and version of each required package, same as with the command above.
```json
{
"require": {
"michelf/php-markdown": ">=1.4",
"ezyang/htmlpurifier": ">=4.6.0"
}
}
```
Once you have edited the `composer.json`, you can invoke Composer to download the updated dependencies. Run
> Depending on the package additional configuration may be required (eg. you have to register a module in the config), but autoloading of the classes should be handled by composer.
Using a specific version of a package
------------------------------------
Yii always comes with the latest version of a required library that it is compatible with, but allows you to use an older version if you need to.
A good example for this is jQuery which has [dropped old IE browser support](http://jquery.com/browser-support/) in version 2.x.
When installing Yii via composer the installed jQuery version will be the latest 2.x release. When you want to use jQuery 1.10
because of IE browser support you can adjust your composer.json by requiring a specific version of jQuery like this:
```json
{
"require": {
...
"yiisoft/jquery": "1.10.*"
}
}
```
FAQ
---
### Getting "You must enable the openssl extension to download files via https"
If you're using WAMP check [this answer at StackOverflow](http://stackoverflow.com/a/14265815/1106908).
### Getting "Failed to clone <URLhere>, git was not found, check that it is installed and in your Path env."
Either install git or try adding `--prefer-dist` to the end of `install` or `update` command.
### Should I Commit The Dependencies In My Vendor Directory?
Short answer: No. Long answer, see [here](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md).
Below are the basic steps you may follow to create an extension.
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
it can be more easily installed and used by other users, liked 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](https://github.com).
Development and maintenance work about the extension should be done on this repository.
The development and maintenance work about the extension should be done on this repository.
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.
3. 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).
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.
### `composer.json`
### `composer.json`<aname="composer-json"></a>
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).
You may also refer to the following example which is the `composer.json` file for the `yiisoft/yii2-imagine` extension:
The following example shows the `composer.json` file for the `yiisoft/yii2-imagine` extension:
```json
{
@ -137,36 +154,38 @@ You may also refer to the following example which is the `composer.json` file fo
}
```
> Info: It is important that you specify the package type as `yii2-extension` so that the package can
be recognized as a Yii extension when being installed.
#### Package Name <aname="package-name"></a>
### Package Names
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.
Each extension, when released as a Composer package, should have a package name which uniquely identifies itself
among all other packages. 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.
Do NOT use `yiisoft` as vendor name as it is reserved for use by the Yii core code.
Do NOT use `yiisoft` as vendor name as this is reserved for use by the Yii core code.
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.
Also, to easily tell from package name whether a package is a Yii extension, we recommend you prefix `yii2-`
to the project name.
#### Package Type <aname="package-type"></a>
### Namespaces
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.
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
Qiang Xue
10 years ago