Commit eb98df2e by Alexander Makarov

Merge pull request #6121 from cdvrooman/patch-5

[skip ci] Update structure-extensions.md
parents 59262052 281bd5ef
...@@ -69,7 +69,7 @@ Image::thumbnail('@webroot/img/test-image.jpg', 120, 120) ...@@ -69,7 +69,7 @@ Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
### Installing Extensions Manually <a name="installing-extensions-manually"></a> ### Installing Extensions Manually <a name="installing-extensions-manually"></a>
In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer. In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer.
To do so, you should To do so, you should:
1. download the extension archive files and unpack them in the `vendor` directory. 1. download the extension archive files and unpack them in the `vendor` directory.
2. install the class autoloaders provided by the extensions, if any. 2. install the class autoloaders provided by the extensions, if any.
...@@ -96,12 +96,12 @@ You may consider creating an extension when you feel the need to share with othe ...@@ -96,12 +96,12 @@ You may consider creating an extension when you feel the need to share with othe
An extension can contain any code you like, such as a helper class, a widget, a module, etc. 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 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. it can be more easily installed and used by other users, as described in the last subsection.
Below are the basic steps you may follow to create an extension as a Composer package. 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). 1. Create a project for your extension and host it on a VCS repository, such as [github.com](https://github.com).
The development and maintenance work about the extension should be done on this repository. The development and maintenance work for 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 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. refer to the next subsection for more details.
3. Register your extension with a Composer repository, such as [Packagist](https://packagist.org/), so that 3. Register your extension with a Composer repository, such as [Packagist](https://packagist.org/), so that
...@@ -161,7 +161,7 @@ Each Composer package should have a package name which uniquely identifies the p ...@@ -161,7 +161,7 @@ Each Composer package should have a package name which uniquely identifies the p
The format of package names is `vendorName/projectName`. For example, in the package name `yiisoft/yii2-imagine`, 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. 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 your vendor name as it 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, 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. `myname/yii2-mywidget`. This will allow users to more easily tell whether a package is a Yii 2 extension.
...@@ -233,7 +233,7 @@ For example, the above `autoload` declaration will correspond to an alias named ...@@ -233,7 +233,7 @@ For example, the above `autoload` declaration will correspond to an alias named
### Recommended Practices <a name="recommended-practices"></a> ### Recommended Practices <a name="recommended-practices"></a>
Because extensions are meant to be used by other people, you often need to take extra development effort. Below Because extensions are meant to be used by other people, you often need to make an extra effort during development. Below
we introduce some common and recommended practices in creating high quality extensions. we introduce some common and recommended practices in creating high quality extensions.
...@@ -247,7 +247,7 @@ Your class namespaces should start with `vendorName\extensionName`, where `exten ...@@ -247,7 +247,7 @@ Your class namespaces should start with `vendorName\extensionName`, where `exten
in the package name except that it should not contain the `yii2-` prefix. For example, for the `yiisoft/yii2-imagine` in the package name except that it should not contain the `yii2-` prefix. For example, for the `yiisoft/yii2-imagine`
extension, we use `yii\imagine` as the namespace for its classes. extension, we use `yii\imagine` as the namespace for its classes.
Do not use `yii`, `yii2` or `yiisoft` as vendor name. These names are reserved for use by the Yii core code. Do not use `yii`, `yii2` or `yiisoft` as your vendor name. These names are reserved for use by the Yii core code.
#### Bootstrapping Classes <a name="bootstrapping-classes"></a> #### Bootstrapping Classes <a name="bootstrapping-classes"></a>
...@@ -356,14 +356,14 @@ You should give each release of your extension a version number (e.g. `1.0.1`). ...@@ -356,14 +356,14 @@ You should give each release of your extension a version number (e.g. `1.0.1`).
#### Releasing <a name="releasing"></a> #### Releasing <a name="releasing"></a>
To let other people know your extension, you need to release it to public. To let other people know about your extension, you need to release it to the public.
If it is the first time you release an extension, you should register it on a Composer repository, such as If it is the first time you are releasing an extension, you should register it on a Composer repository, such as
[Packagist](https://packagist.org/). After that, all you need to do is simply creating a release tag (e.g. `v1.0.1`) [Packagist](https://packagist.org/). After that, all you need to do is simply create a release tag (e.g. `v1.0.1`)
on the VCS repository of your extension and notify the Composer repository about the new release. People will on the VCS repository of your extension and notify the Composer repository about the new release. People will
then be able to find the new release, and install or update the extension through the Composer repository. then be able to find the new release, and install or update the extension through the Composer repository.
In the releases of your extension, besides code files you should also consider including the followings to In the releases of your extension, in addition to code files, you should also consider including the following to
help other people learn about and use your extension: help other people learn about and use your extension:
* A readme file in the package root directory: it describes what your extension does and how to install and use it. * A readme file in the package root directory: it describes what your extension does and how to install and use it.
...@@ -375,7 +375,7 @@ help other people learn about and use your extension: ...@@ -375,7 +375,7 @@ help other people learn about and use your extension:
of the extension. The file may be written in Markdown format and named as `upgrade.md`. of the extension. The file may be written in Markdown format and named as `upgrade.md`.
* Tutorials, demos, screenshots, etc.: these are needed if your extension provides many features that cannot be * Tutorials, demos, screenshots, etc.: these are needed if your extension provides many features that cannot be
fully covered in the readme file. fully covered in the readme file.
* API documentation: your code should be well documented to allow other people more easily read and understand it. * API documentation: your code should be well documented to allow other people to more easily read and understand it.
You may refer to the [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php) You may refer to the [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php)
to learn how to document your code. to learn how to document your code.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment