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
----------
- Extension code style SHOULD be similar to [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
- 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()]]`.
- If you're displaying errors to developers do not translate these (i.e. do not use `\Yii::t()`). Errors should be
translated only if they're displayed to end users.
- Extension SHOULD NOT use class prefixes (i.e. `TbNavBar`, `EMyWidget`, etc.)
- Extension classes should not be prefixed. No `TbNavBar`, `EMyWidget`, etc.
### Namespace
- Extension MUST NOT use `yiisoft` in the namespaces used in the package.
- Extension MUST NOT have a root-namespace named `\yii`, `\yii2` or `\yiisoft`.
- Extension SHOULD use namespaces in this format `vendor-name\type` (all lowercase).
- Do not use `yiisoft` in the namespaces.
- Do not use `\yii`, `\yii2` or `\yiisoft` as root namespace.
- Use `vendor-name\type` namespace format (all lowercase).
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`
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 MUST be registered at [Packagist](https://packagist.org). 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`.
- 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.
### Composer package name
@ -53,14 +48,15 @@ In the above:
### Versioning
- Extension SHOULD follow 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 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
- Extension MUST use the type `yii2-extension` in `composer.json` file.
- Extension MUST NOT use `yii` or `yii2` in their composer vendor name.
- Extension MUST NOT use `yiisoft` in the composer package name or the composer vendor name.
- 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.
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.
- Migrations SHOULD be DBMS agnostic.
- You MUST NOT make use of active-record model classes in your migrations.
- Migrations should be appliable to as many data storages as possible.
- Do not use active record models in your migrations.
Assets
------
- Asset files MUST be registered through Bundles.
- Register assets [through bundles](assets.md).
Events
------
@ -116,16 +112,11 @@ TBD
i18n
----
- Extension SHOULD provide at least one message catalogue with either source or target language in English.
- Extension MAY provide a configuration for creating message catalogues.
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\*`
- If extension outputs messages intended for end user these should be wrapped into `Yii::t()` in order to be translatable.
- Exceptions and other developer-oriented message should not be translated.
- Consider proving `config.php` for `yii message` command to simplify translation.
Testing your extension
----------------------
- Extension SHOULD be testable with *PHPUnit*.
- Consider adding unit tests for PHPUnit.

Loading…
Cancel
Save