The Yii framework was designed to be easily extendable. 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
----------
- Use [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style).
- Document classes, methods and properties using phpdoc. Note that you can use markdown and link to properties and methods
using the following syntax: e.g. `[[name()]]`, `[[name\space\MyClass::name()]]`.
- Extension classes should not be prefixed. No `TbNavBar`, `EMyWidget`, etc.
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
- Do not use `yiisoft` in the namespaces.
- Do not use `\yii`, `\yii2` or `\yiisoft` as root namespace.
- Namespace should be `vendorName\uniqueName`.
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 unique namespace is important to prevent name collisions and autoload faster. Examples:
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`
...
...
@@ -24,15 +29,22 @@ Choosing unique namespace is important to prevent name collisions and autoload f
Distribution
------------
- There should be a `readme.md` file clearly describing what extension does in English, its requirements, how to install
and use it. It should be written using markdown. If you want to provide translated readme, name it as `readme_ru.md`
where `ru` is your language code. If extension provides a widget it is a good idea to include some screenshots.
- It is recommended to host your extensions at [Github](github.com).
- Extension should be registered at [Packagist](https://packagist.org) in order to be installable via Composer.
Choose package name wisely since changing it leads to losing stats and inability to install package by the old name.
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](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:
...
...
@@ -40,32 +52,35 @@ name it like the following:
yii2-my-extension-name-type
```
In the above:
Where:
-`yii2-` prefix.
-Extension name lowecase, words separated by `-`.
-`-type` postfix where type may be `widget`, `behavior`, `module` etc.
-`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
- Additional code, eg. libraries, should be required in your `composer.json` file.
- When extension is released in a stable version, its requirements should not include `dev` packages that do not
have a `stable` release.
- Use appropriate version constraints, eg. `1.*`, `@stable` for requirements.
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 composer vendor name.
- Do not use `yiisoft` in the composer package name or the composer vendor name.
- 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 repository root use PSR-4 the following way in your `composer.json`:
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:
```
{
...
...
@@ -92,19 +107,21 @@ If your extension classes reside directly in repository root use PSR-4 the follo
}
```
In the above `myname/mywidget` is the package name that will be registered
at [Packagist](https://packagist.org). It is common for it to match your github repository.
In the above,`myname/mywidget` is the package name that will be registered
at [Packagist](https://packagist.org). It is common for the package name to match your Github repository name.
We're using `psr-4` autoloader and mapping `myname\mywidget` namespace to the root directory where our classes reside.
In the above, the `psr-4` autoloader is specified, mapping the `myname\mywidget` namespace to the root directory where the classes reside.
More details can be found in the [composer documentation](http://getcomposer.org/doc/04-schema.md#autoload).
More details on this syntax can be found in the [Composer documentation](http://getcomposer.org/doc/04-schema.md#autoload).
Working with database
---------------------
- If extension creates or modifies database schema always use Yii migrations instead of SQL files or custom scripts.
- Migrations should be appliable to as many data storages as possible.
- Do not use active record models in your migrations.
Extensions sometimes have to use their own database tables. In such situations,
- If the extension creates or modifies the database schema, always use Yii migrations instead of SQL files or custom scripts.
- Migrations should be applicable to as many data storages as possible.
- Do not use Active Record models in your migrations.
