From 1f1e3cb9e015cfa3ad96e15cd7218d1fc745e32c Mon Sep 17 00:00:00 2001 From: unknown <651125386@qq.com> Date: Fri, 6 Mar 2015 16:35:39 +0800 Subject: [PATCH] update-structure-extensions.md --- docs/guide-zh-CN/structure-extensions.md | 201 +++++++++++------------ 1 file changed, 100 insertions(+), 101 deletions(-) diff --git a/docs/guide-zh-CN/structure-extensions.md b/docs/guide-zh-CN/structure-extensions.md index b0d472af80..e2fac9c626 100644 --- a/docs/guide-zh-CN/structure-extensions.md +++ b/docs/guide-zh-CN/structure-extensions.md @@ -1,36 +1,35 @@ -Extensions +扩展 ========== -Extensions are redistributable software packages specifically designed to be used in Yii applications and provide -ready-to-use features. For example, the [yiisoft/yii2-debug](tool-debugger.md) extension adds a handy debug toolbar -at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can -use extensions to accelerate your development process. You can also package your code as extensions to share with -other people your great work. +扩展是可再发行的软件包，专门设计用在Yii应用中，并具有可随时调用的特点。例如， +在应用的每个页面底部为 [yiisoft/yii2-debug](tool-debugger.md) 扩展增加一个方便调试的工具栏 +这会使得你更加容易掌握这些页面是如何生成的。你可以运用扩展模块来加速你的开发进程你也可以将代码打包成扩展文件形式， +来与其他人共享你的工作成果. -> Info: We use the term "extension" to refer to Yii-specific software packages. For general purpose software packages - that can be used without Yii, we will refer to them using the term "package" or "library". +> 提示信息: 我们用术语 "extension" 来特指 Yii 特定软件包。对于那些无需 Yii 就能使用的通用软件包 + 我们会用”包”或”库”这样的术语来表示它们。 -## Using Extensions +## 运用扩展 -To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/) -packages which can be installed by taking the following two simple steps: +为了使用扩展，你首先需要安装它。大部分扩展文件会用 [Composer](https://getcomposer.org/) +包来部署，Composer 包可以用以下两个简单的步骤安装： -1. modify the `composer.json` file of your application and specify which extensions (Composer packages) you want to install. -2. run `composer install` to install the specified extensions. +1. 移除你应用中的 `composer.json` 文件，并指定你要安装的扩展文件 (Composer packages)。 +2. 运行 `composer install` 来安装指定的扩展文件。 -Note that you may need to install [Composer](https://getcomposer.org/) if you do not have it. +提示：如果没有的话你需要安装 [Composer](https://getcomposer.org/)。 -By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository -for open source Composer packages. You can look for extensions on Packagist. You may also +默认情况下，Composer 安装包注册在 [Packagist](https://packagist.org/) - 最大的开源 +Composer 包库。你可以对照着看一下 Packagist 扩展。You may also [create your own repository](https://getcomposer.org/doc/05-repositories.md#repository) and configure Composer to use it. This is useful if you are developing closed open extensions and want to share within your projects. Extensions installed by Composer are stored in the `BasePath/vendor` directory, where `BasePath` refers to the -application's [base path](structure-applications.md#basePath). Because Composer is a dependency manager, when -it installs a package, it will also install all its dependent packages. +application's [base path](structure-applications.md#basePath). Because Composer is a dependency manager, 如果 +安装一个包，也要安装它所有的附属包。 -For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following: +例如，为了安装 `yiisoft/yii2-imagine` 扩展，按如下方式修改 `composer.json` 文件： ```json { @@ -44,15 +43,15 @@ For example, to install the `yiisoft/yii2-imagine` extension, modify your `compo } ``` -After the installation, you should see the directory `yiisoft/yii2-imagine` under `BasePath/vendor`. You should -also see another directory `imagine/imagine` which contains the installed dependent package. +安装完成后，需要查看 `BasePath/vendor` 下的 `yiisoft/yii2-imagine` 目录。同时需要查看 +包含安装附属包的 `imagine/imagine` 目录。 -> Info: The `yiisoft/yii2-imagine` is a core extension developed and maintained by the Yii developer team. All +> 提示信息：`yiisoft/yii2-imagine` 是由 Yii 团队开发和维护的一个核心扩展。All core extensions are hosted on [Packagist](https://packagist.org/) and named like `yiisoft/yii2-xyz`, where `xyz` varies for different extensions. -Now you can use the installed extensions like they are part of your application. The following example shows -how you can use the `yii\imagine\Image` class provided by the `yiisoft/yii2-imagine` extension: +Now you can use the installed extensions like they are part of your application. 下面的例子展示了 +如何运用由 `yiisoft/yii2-imagine` 扩展提供的 `yii\imagine\Image` 类： ```php use Yii; @@ -63,20 +62,20 @@ Image::thumbnail('@webroot/img/test-image.jpg', 120, 120) ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]); ``` -> Info: Extension classes are autoloaded by the [Yii class autoloader](concept-autoloading.md). +> 提示信息：扩展类由 [Yii class autoloader](concept-autoloading.md) 自动加载。 -### Installing Extensions Manually +### 手动安装扩展 -In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer. -To do so, you should +某些特殊情况下，可能需要手动安装部分或全部扩展，而不是依靠 Composer。 +方法如下 -1. download the extension archive files and unpack them in the `vendor` directory. -2. install the class autoloaders provided by the extensions, if any. -3. download and install all dependent extensions as instructed. +1. 下载扩展存档文件并解压到 `vendor` 目录。 +2. 如果有的话，安装由扩展提供的类自动加载器。 +3. 下载并按照说明安装所有相关扩展文件。 -If an extension does not have a class autoloader but follows the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/), -you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to +如果一个扩展没有一个自动载入的类但是遵循 [PSR-4 standard](http://www.php-fig.org/psr/psr-4/), +你可以用yii提供的自动载入类去载入这个扩展类。All you need to do is just to declare a [root alias](concept-aliases.md#defining-aliases) for the extension root directory. For example, assuming you have installed an extension in the directory `vendor/mycompany/myext`, and the extension classes are under the `myext` namespace, then you can include the following code in your application configuration: @@ -90,15 +89,15 @@ are under the `myext` namespace, then you can include the following code in your ``` -## Creating Extensions +## 创建扩展 -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. +如果你想和别人共享自己的代码，可以考虑创建一个扩展。 +这个扩展能够容纳任何代码，例如一个助手类，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. +按照下边步骤为 Composer 包创建一个扩展。 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. @@ -110,9 +109,9 @@ Below are the basic steps you may follow to create an extension as a Composer pa ### `composer.json` -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). -The following example shows the `composer.json` file for the `yiisoft/yii2-imagine` extension: +每一个 Composer package 的根目录包都必须包含一个 `composer.json` 文件。The file contains the metadata about +the package. 可以在 [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup) 手册内找到有关该文件完整的说明。 +下边例子展示了 `composer.json` 文件的 `yiisoft/yii2-imagine` 扩展： ```json { @@ -157,8 +156,8 @@ The following example shows the `composer.json` file for the `yiisoft/yii2-imagi #### Package Name -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`, +每一个 Composer 包的名称中都需要包含一个唯一标识，以便容易识别。 +The format of package names is `vendorName/projectName`. 例如，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. @@ -172,15 +171,15 @@ We recommend you prefix `yii2-` to the project name for packages representing Yi 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. -When a user runs `composer install` to install an extension, the file `vendor/yiisoft/extensions.php` -will be automatically updated to include the information about the new extension. From this file, Yii applications -can know which extensions are installed (the information can be accessed via [[yii\base\Application::extensions]]. +当用户运行 `composer install` 来安装扩展，`vendor/yiisoft/extensions.php`文件 +将被自动更新，包括对新扩展。从这个文件中，可以知道 Yii 应用 +安装了哪些扩展 (the information can be accessed via [[yii\base\Application::extensions]]. #### Dependencies -Your extension depends on Yii (of course). So you should list it (`yiisoft/yii2`) in the `require` entry in `composer.json`. -If your extension also depends on other extensions or third-party libraries, you should list them as well. +您的扩展依赖于 Yii (of course)。So you should list it (`yiisoft/yii2`) in the `require` entry in `composer.json`. +如果您的扩展依赖于其它扩展或者第三方库，你也要将它们罗列出来。 Make sure you also list appropriate version constraints (e.g. `1.*`, `@stable`) for each dependent package. Use stable dependencies when your extension is released in a stable version. @@ -198,19 +197,19 @@ simply list the dependency in `composer.json` like the following: } ``` -The above code states that the extension depends on the `jquery` Bower package. In general, you can use +上面的代码中指出此扩展依赖于 `jquery` Bower package。一般来说，you can use `bower-asset/PackageName` to refer to a Bower package in `composer.json`, and use `npm-asset/PackageName` to refer to a NPM package. When Composer installs a Bower or NPM package, by default the package content will be installed under the `@vendor/bower/PackageName` and `@vendor/npm/Packages` directories, respectively. These two directories can also be referred to using the shorter aliases `@bower/PackageName` and `@npm/PackageName`. -For more details about asset management, please refer to the [Assets](structure-assets.md#bower-npm-assets) section. +更多关于资源管理的细节，请参考 [Assets](structure-assets.md#bower-npm-assets) 部分。 #### Class Autoloading In order for your classes to be autoloaded by the Yii class autoloader or the Composer class autoloader, -you should specify the `autoload` entry in the `composer.json` file, like shown below: +you should specify the `autoload` entry in the `composer.json` file, 如下： ```json { @@ -226,9 +225,9 @@ you should specify the `autoload` entry in the `composer.json` file, like shown You may list one or multiple root namespaces and their corresponding file paths. -When the extension is installed in an application, Yii will create for each listed root namespace +当在一个应用中安装一个扩展时，Yii will create for each listed root namespace an [alias](concept-aliases.md#extension-aliases) that refers to the directory corresponding to the namespace. -For example, the above `autoload` declaration will correspond to an alias named `@yii/imagine`. +例如，the above `autoload` declaration will correspond to an alias named `@yii/imagine`. ### Recommended Practices @@ -237,9 +236,9 @@ Because extensions are meant to be used by other people, you often need to take we introduce some common and recommended practices in creating high quality extensions. -#### Namespaces +#### 命名空间 -To avoid name collisions and make the classes in your extension autoloadable, you should use namespaces and +为了避免名字冲突和使得扩展里的类能自动加载，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 [PSR-0 standard](http://www.php-fig.org/psr/psr-0/). @@ -247,18 +246,18 @@ You class namespaces should start with `vendorName\extensionName`, where `extens 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 its classes. -Do not use `yii`, `yii2` or `yiisoft` as vendor name. These names are reserved for use by the Yii core code. +不要将 `yii`, `yii2` or `yiisoft` 作为 vendor 名称。这些名称是保留给 Yii 核心代码使用的。 #### Bootstrapping Classes -Sometimes, you may want your extension to execute some code during the [bootstrapping process](runtime-bootstrapping.md) -stage of an application. For example, your extension may want to respond to the application's `beginRequest` event +某些时候，you may want your extension to execute some code during the [bootstrapping process](runtime-bootstrapping.md) +stage of an application. 例如，your extension may want to respond to the application's `beginRequest` event to adjust some environment settings. While you can instruct users of the extension to explicitly attach your event -handler in the extension to the `beginRequest` event, a better way is to do this automatically. +handler in the extension to the `beginRequest` event, 最好能够将这个过程自动化。 -To achieve this goal, you can create a so-called *bootstrapping class* by implementing [[yii\base\BootstrapInterface]]. -For example, +为了实现这一目标，you can create a so-called *bootstrapping class* by implementing [[yii\base\BootstrapInterface]]. +例如， ```php namespace myname\mywidget; @@ -289,29 +288,29 @@ You then list this class in the `composer.json` file of your extension like foll } ``` -When the extension is installed in an application, Yii will automatically instantiate the bootstrapping class +当在一个应用中安装一个扩展时，Yii will automatically instantiate the bootstrapping class and call its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method during the bootstrapping process for every request. #### Working with Databases -Your extension may need to access databases. Do not assume that the applications that use your extension will always -use `Yii::$db` as the DB connection. Instead, you should declare a `db` property for the classes that require DB access. +你的扩展可能需要访问数据库。Do not assume that the applications that use your extension will always +use `Yii::$db` as the DB connection. 反而，you should declare a `db` property for the classes that require DB access. The property will allow users of your extension to customize which DB connection they would like your extension to use. -As an example, you may refer to the [[yii\caching\DbCache]] class and see how it declares and uses the `db` property. +举个例子，you may refer to the [[yii\caching\DbCache]] class and see how it declares and uses the `db` property. -If your extension needs to create specific DB tables or make changes to DB schema, you should +如果你的扩展需要创建一个详细的 DB tables 或者 要改变 DB schema，需要 -- provide [migrations](db-migrations.md) to manipulate DB schema, rather than using plain SQL files; -- try to make the migrations applicable to different DBMS; -- avoid using [Active Record](db-active-record.md) in the migrations. +- 提供 [migrations](db-migrations.md) 来操控 DB schema，而不是使用普通的 SQL 文件； +- 尝试让迁移能够适应不同的 DBMS； +- 避免使用 migrations 中的 [Active Record](db-active-record.md)。 #### Using Assets -If your extension is a widget or a module, chances are that it may require some [assets](structure-assets.md) to work. -For example, a module may display some pages which contain images, JavaScript, and CSS. Because the files of an +如果你的扩展是 a widget 或者 a module，chances are that it may require some [assets](structure-assets.md) to work. +例如，可能会显示一些包含 images, JavaScript, and CSS 的页面。Because the files of an extension are all under the same directory which is not Web accessible when installed in an application, you have two choices to make the asset files directly accessible via Web: @@ -325,7 +324,7 @@ Please refer to the [Assets](structure-assets.md) section for more details about #### Internationalization and Localization -Your extension may be used by applications supporting different languages! Therefore, if your extension displays +Your extension may be used by applications supporting different languages! 因此，if your extension displays content to end users, you should try to [internationalize and localize](tutorial-i18n.md) it. In particular, - If the extension displays messages intended for end users, the messages should be wrapped into `Yii::t()` @@ -334,66 +333,66 @@ content to end users, you should try to [internationalize and localize](tutorial - If the extension displays numbers, dates, etc., they should be formatted using [[yii\i18n\Formatter]] with appropriate formatting rules. -For more details, please refer to the [Internationalization](tutorial-i18n.md) section. +了解更多细节，请参考 [Internationalization](tutorial-i18n.md) 部分的内容。 -#### Testing +#### 测试 -You want your extension to run flawlessly without bringing problems to other people. To reach this goal, you should -test your extension before releasing it to public. +如果你想要让你的扩展没有后顾之忧地完美运行。为了达到这个目的，你应该 +在发布扩展前先测试它。 It is recommended that you create various test cases to cover your extension code rather than relying on manual tests. -Each time before you release a new version of your extension, you may simply run these test cases to make sure -everything is in good shape. Yii provides testing support, which can help you to more easily write unit tests, -acceptance tests and functionality tests. For more details, please refer to the [Testing](test-overview.md) section. +每次在你发布新版本的扩展之前，你应该简单地运行这些测试案例 +everything is in good shape. Yii 提供了测试支持，可以帮你更容易写单元测试， +验收测试和功能测试。更多详细内容，请参考 [Testing](test-overview.md) 部分。 #### Versioning -You should give each release of your extension a version number (e.g. `1.0.1`). We recommend you follow the +你应该给每个扩展的发布配置一个版本号 (e.g. `1.0.1`)。We recommend you follow the [semantic versioning](http://semver.org) practice when determining what version numbers should be used. #### Releasing -To let other people know your extension, you need to release it to public. +为了让其他人知道你的版本，你需要将它公之于众。 -If it is the first time you release 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`) +如果这是你第一次发布一个扩展，你应该先在 Composer 库里注册，比如 +[Packagist](https://packagist.org/)。 After that, all you need to do is simply creating 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 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 -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. +* 在包根目录里的 readme 文件：它描述了你的扩展功能以及如何安装和使用. We recommend you write it in [Markdown](http://daringfireball.net/projects/markdown/) format and name the file as `readme.md`. -* A changelog file in the package root directory: it lists what changes are made in each release. The file - may be written in Markdown format and named as `changelog.md`. -* An upgrade file in the package root directory: it gives the instructions on how to upgrade from older releases - 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 +* 在包根目录中更新日志文件：它列出了每个版本所做的变化。文件 + 可以被写成 Markdown 格式并命名为 `changelog.md`。 +* 在包根目录下升级文件：它提供了有关如何从旧版本升级 + 的说明。该文件可以被写成 Markdown 格式并命名为 `upgrade.md`。 +* 教程，demos, screenshots, etc.: these are needed if your extension provides many features that cannot be fully covered in the readme file. -* API documentation: your code should be well documented to allow other people 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) - to learn how to document your code. +* API documentation:你的代码应该好好地记录下来。 + 你可以参考 [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php) + 来学习如何记录代码。 -> Info: Your code comments can be written in Markdown format. The `yiisoft/yii2-apidoc` extension provides a tool - for you to generate pretty API documentation based on your code comments. +> 提示信息：你代码中的注释可以写成 Markdown 格式。`yiisoft/yii2-apidoc` 扩展为你提供了一 + 个基于代码注释生成的完美 API 文档工具。 -> Info: While not a requirement, we suggest your extension adhere to certain coding styles. You may refer to - the [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). +> 提示信息：虽然不是必须的，我们仍建议你的应保持统一的代码风格。可以 + 参考 [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style)。 ## Core Extensions -Yii provides the following core extensions that are developed and maintained by the Yii developer team. They are all -registered on [Packagist](https://packagist.org/) and can be easily installed as described in the -[Using Extensions](#using-extensions) subsection. +Yii 提供了以下核心扩展，这些扩展是由 Yii 开发团队维护和开发。它们都是在 +[Packagist](https://packagist.org/) 注册的并且可以很容易的被安装在 +[Using Extensions](#using-extensions) 部分中。 - [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc): - provides an extensible and high-performance API documentation generator. It is also used to generate the core + 提供一个可扩展并且是高性能的 API 文档生成器。It is also used to generate the core framework API documentation. - [yiisoft/yii2-authclient](https://github.com/yiisoft/yii2-authclient): provides a set of commonly used auth clients, such as Facebook OAuth2 client, GitHub OAuth2 client.