Browse Source

Made extensions guide more human-friendly and more specific

tags/2.0.0-beta
Alexander Makarov 11 years ago
parent
commit
ce1c702424
  1. 51
      docs/guide/extensions.md

51
docs/guide/extensions.md

@ -4,19 +4,16 @@ Extending Yii
Code style Code style
---------- ----------
- Extension code style SHOULD be similar to [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). - Use [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style).
- All classes, methods and properties SHOULD be documented using phpdoc. Note that you can use markdown and link to properties and methods - 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()]]`. using the following syntax: e.g. `[[name()]]`, `[[name\space\MyClass::name()]]`.
- If you're displaying errors to developers do not translate these (i.e. do not use `\Yii::t()`). Errors should be - Extension classes should not be prefixed. No `TbNavBar`, `EMyWidget`, etc.
translated only if they're displayed to end users.
- Extension SHOULD NOT use class prefixes (i.e. `TbNavBar`, `EMyWidget`, etc.)
### Namespace ### Namespace
- Extension MUST NOT use `yiisoft` in the namespaces used in the package. - Do not use `yiisoft` in the namespaces.
- Extension MUST NOT have a root-namespace named `\yii`, `\yii2` or `\yiisoft`. - Do not use `\yii`, `\yii2` or `\yiisoft` as root namespace.
- Extension SHOULD use namespaces in this format `vendor-name\type` (all lowercase). - Use `vendor-name\type` namespace format (all lowercase).
Distribution Distribution
------------ ------------
@ -25,10 +22,8 @@ Distribution
and use it. It should be written using markdown. If you want to provide translated readme, name it as `readme_ru.md` 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. 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). - It is recommended to host your extensions at [Github](github.com).
- Extension MUST be registered at [Packagist](https://packagist.org). Choose package name wisely since changing it leads - Extension should be registered at [Packagist](https://packagist.org) in order to be installable via Composer.
to losing stats and inability to install package by the old name. Choose package name wisely since changing it leads to losing stats and inability to install package by the old name.
- Extension MUST provide a valid autoloading configuration in `composer.json`.
### Composer package name ### Composer package name
@ -53,14 +48,15 @@ In the above:
### Versioning ### Versioning
- Extension SHOULD follow the rules of [semantic versioning](http://semver.org). - 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`. - 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 ### composer.json
- Extension MUST use the type `yii2-extension` in `composer.json` file. - Use the type `yii2-extension` in `composer.json` file if your extension is Yii-specific.
- Extension MUST NOT use `yii` or `yii2` in their composer vendor name. - Do not use `yii` or `yii2` as composer vendor name.
- Extension MUST NOT use `yiisoft` in the composer package name or 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 repository root use PSR-4 the following way in your `composer.json`:
@ -100,13 +96,13 @@ Working with database
--------------------- ---------------------
- If extension creates or modifies database schema always use Yii migrations instead of SQL files or custom scripts. - If extension creates or modifies database schema always use Yii migrations instead of SQL files or custom scripts.
- Migrations SHOULD be DBMS agnostic. - Migrations should be appliable to as many data storages as possible.
- You MUST NOT make use of active-record model classes in your migrations. - Do not use active record models in your migrations.
Assets Assets
------ ------
- Asset files MUST be registered through Bundles. - Register assets [through bundles](assets.md).
Events Events
------ ------
@ -116,16 +112,11 @@ TBD
i18n i18n
---- ----
- Extension SHOULD provide at least one message catalogue with either source or target language in English. - If extension outputs messages intended for end user these should be wrapped into `Yii::t()` in order to be translatable.
- Extension MAY provide a configuration for creating message catalogues. - Exceptions and other developer-oriented message should not be translated.
- Consider proving `config.php` for `yii message` command to simplify translation.
Authorization
-------------
- Auth-items for controllers SHOULD be named after the following format `vendor\ext\controller\action`.
- Auth-items names may be shortened using an asterisk, eg. `vendor\ext\*`
Testing your extension Testing your extension
---------------------- ----------------------
- Extension SHOULD be testable with *PHPUnit*. - Consider adding unit tests for PHPUnit.

Loading…
Cancel
Save