默認情況，Composer安裝的是在 Packagist 中注冊的軟件包 - 最大的開源 Composer 代碼庫。你可以在 Packageist 中查找擴展。你也可以創(chuàng)建你自己的代碼庫然后配置 Composer 來使用它。如果是在開發(fā)私有的擴展，并且想只在你的其他工程中共享時，這樣做是很有用的。

通過 Composer 安裝的擴展會存放在 BasePath/vendor 目錄下，這里的 BasePath 指你的應用的 base path。因為 Composer 還是一個依賴管理器，當它安裝一個包時，也將安裝這個包所依賴的所有軟件包。

例如想安裝 yiisoft/yii2-imagine 擴展，可按如下示例修改你的 composer.json 文件：

{
    // ...

    "require": {
        // ... other dependencies

        "yiisoft/yii2-imagine": "*"
    }
}

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.

Info: The yiisoft/yii2-imagine is a core extension developed and maintained by the Yii developer team. All core extensions are hosted on Packagist 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:

安裝完成后，你應該能在 BasePath/vendor 目錄下見到 yiisoft/yii2-imagine 目錄。你也應該見到另一個 imagine/imagine 目錄，在其中安裝了所依賴的包。

信息： yiisoft/yii2-imagine 是 Yii 由開發(fā)團隊維護一個核心擴展，所有核心擴展均由 Packagist 集中管理，命名為yiisoft/yii2-xyz，其中的 xyz，不同擴展有不同名稱。

現在你可以使用安裝好的擴展了，好比是應用的一部分。如下示例展示了如何使用 yiisoft/yii2-imagine 擴展提供的 yii\imagine\Image 類：

use Yii;
use yii\imagine\Image;

<<<<<<< HEAD
// generate a thumbnail image
// 生成一個縮略圖
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.

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

download the extension archive files and unpack them in the vendor directory.
install the class autoloaders provided by the extensions, if any.
download and install all dependent extensions as instructed.

If an extension does not have a class autoloader but follows the PSR-4 standard, you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to declare a root alias 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:

信息：擴展類由 Yii class autoloader 自動加載。

手動安裝擴展

在極少情況下，你可能需要手動安裝一部分或者全部擴展，而不是依賴 Composer。想做到這一點，你應當：

下載擴展壓縮文件，解壓到 vendor 目錄。
如果有，則安裝擴展提供的自動加載器。
按指導說明下載和安裝所有依賴的擴展。

如果擴展沒有提供類的自動加載器，但也遵循了 PSR-4 standard 標準，那么你可以使用 Yii 提供的類自動加載器來加載擴展類。你需要做的僅僅是為擴展的根目錄聲明一個 root alias。例如，假設在 vendor/mycompany/myext 目錄中安裝了一個擴展，并且擴展類的命名空間為 myext ，那么你可以在應用配置文件中包含如下代碼：

[
    'aliases' => [
        '@myext' => '@vendor/mycompany/myext',
    ],
]

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.

It is recommended that you create an extension in terms of a Composer package 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.

Create a project for your extension and host it on a VCS repository, such as github.com. The development and maintenance work about the extension should be done on this repository.
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.
Register your extension with a Composer repository, such as Packagist, so that other users can find and install your extension using Composer.

創(chuàng)建擴展

在你需要將你的杰作分享給其他人的時候，你可能會考慮創(chuàng)建一個擴展。擴展可包括任何你喜歡的代碼，例如助手類、掛件、模塊，等等。

建議你按照 Composer package 的條款創(chuàng)建擴展，以便其他人更容易安裝和使用。就像上面的章節(jié)講述的那樣。

以下是將擴展創(chuàng)建為一個 Composer 軟件包的需遵循的基本步驟。

為你的擴展建一個工程，并將它存放在版本控制代碼庫中，例如 github.com 。擴展的開發(fā)和維護都應該在這個代碼庫中進行。
在工程的根目錄下，建一個 Composer 所需的名為 composer.json 的文件。詳情請參考后面的章節(jié)。
在一個 Composer 代碼庫中注冊你的擴展，比如在 Packagist 中，以便其他用戶能找到以及用 Composer 安裝你的擴展。

`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. The following example shows the composer.json file for the yiisoft/yii2-imagine extension:

每個 Composer 軟件包在根目錄都必須有一個 composer.json 文件。該文件包含軟件包的元數據。你可以在 Composer手冊中找到完整關于該文件的規(guī)格。以下例子展示了 yiisoft/yii2-imagine 擴展的 composer.json 文件。

{
    // package name
    "name": "yiisoft/yii2-imagine",

    // package type
    "type": "yii2-extension",

    "description": "The Imagine integration for the Yii framework",
    "keywords": ["yii2", "imagine", "image", "helper"],
    "license": "BSD-3-Clause",
    "support": {
        "issues": "https://github.com/yiisoft/yii2/issues?labels=ext%3Aimagine",
        "forum": "http://www.yiiframework.com/forum/",
        "wiki": "http://www.yiiframework.com/wiki/",
        "irc": "irc://irc.freenode.net/yii",
        "source": "https://github.com/yiisoft/yii2"
    },
    "authors": [
        {
            "name": "Antonio Ramirez",
            "email": "amigo.cobos@gmail.com"
        }
    ],

    // package dependencies
    "require": {
        "yiisoft/yii2": "*",
        "imagine/imagine": "v0.5.0"
    },

    // class autoloading specs
    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}

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, 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.

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.

Package Type

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]].

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. 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.

Most JavaScript/CSS packages are managed using Bower and/or NPM, instead of Composer. Yii uses the Composer asset plugin to enable managing these kinds of packages through Composer. If your extension depends on a Bower package, you can simply list the dependency in composer.json like the following:

包名

每個 Composer 軟件包都應當有一個唯一的包名以便能從其他的軟件包中識別出來。包名的格式為 vendorName/projectName 。例如在包名 yiisoft/yii2-imagine 中，vendor 名和 project 名分別是yiisoft 和 yii2-imagine 。

不要用 yiisoft 作為你的 vendor 名，由于它被 Yii 的核心代碼預留使用了。

我們推薦你用 yii2- 作為你的包名的前綴，表示它是 Yii 2 的擴展，例如，myname/yii2-mywidget。這更便于用戶辨別是否是 Yii 2 的擴展。

包類型

將你的擴展指明為 yii2-extension 類型很重要，以便安裝的時候能被識別出是一個 Yii 擴展。

當用戶運行 composer install 安裝一個擴展時， vendor/yiisoft/extensions.php 文件會被自動更新使之包含新擴展的信息。從該文件中， Yii 應用程序就能知道安裝了哪些擴展 (這些信息可通過 [[yii\base\Application::extensions]] 訪問)。

依賴

你的擴展依賴于 Yii （理所當然）。因此你應當在 composer.json 文件中列出它(yiisoft/yii2)。如果你的擴展還依賴其他的擴展或者是第三方庫，你也要一并列出來。確定你也為每一個依賴的包列出了適當的版本約束條件 (比如 1.*, @stable) 。當你發(fā)布一個穩(wěn)定版本時，你所依賴的包也應當使用穩(wěn)定版本。

大多數 JavaScript/CSS 包是用 Bower 來管理的，而非 Composer。你可使用 Composer asset 插件使之可以通過 Composer 來管理這類包。如果你的擴展依賴 Bower 軟件包，你可以如下例所示那樣簡單地在 composer.json 文件的依賴中列出它。

{
    // package dependencies
    "require": {
        "bower-asset/jquery": ">=1.11.*"
    }
}

The above code states that the extension depends on the jquery Bower package. In general, 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 section.

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:

上述代碼表明該擴展依賴于 jquery Bower 包。一般來說，你可以在 composer.json 中用 bower-asset/PackageName 指定 Bower 包，用 npm-asset/PackageName 指定 NPM 包。當 Compower 安裝 Bower 和 NPM 軟件包時，包的內容默認會分別安裝到 @vendor/bower/PackageName和 @vendor/npm/Packages 下。這兩個目錄還可以分別用 @bower/PackageName 和 @npm/PackageName 別名指向。

關于 asset 管理的詳細情況，請參照 Assets 章節(jié)。

類的自動加載

為使你的類能夠被 Yii 的類自動加載器或者 Composer 的類自動加載器自動加載，你應當在 composer.json 中指定 autoload 條目，如下所示：

{
    // ....

    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}

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 an alias that refers to the directory corresponding to the namespace. For example, the above autoload declaration will correspond to an alias named @yii/imagine.

Recommended Practices

Because extensions are meant to be used by other people, you often need to take extra development effort. Below 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 name the classes in your extension by following the PSR-4 standard or PSR-0 standard.

You class namespaces should start with vendorName\extensionName, where extensionName is similar to the project name 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.

Bootstrapping Classes

Sometimes, you may want your extension to execute some code during the bootstrapping process stage of an application. For example, 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.

To achieve this goal, you can create a so-called bootstrapping class by implementing [[yii\base\BootstrapInterface]]. For example,

你可以列出一個或者多個根命名空間和它們的文件目錄。

當擴展安裝到應用中后，Yii 將為每個所列出根命名空間創(chuàng)建一個別名指向命名空間對應的目錄。例如，上述的 autoload 條目聲明將對應于別名 @yii/imagine。

推薦的做法

擴展意味著會被其他人使用，你在開發(fā)中通常需要額外的付出。下面我們介紹一些通用的及推薦的做法，以創(chuàng)建高品質的擴展。

命名空間

為避免沖突以及使你的擴展中的類能被自動加載，你的類應當使用命名空間，并使類的命名符合 PSR-4 standard 或者 PSR-0 standard 標準。

你的類的命名空間應以 vendorName\extensionName 起始，其中 extensionName 和項目名相同，除了它沒有 yii2- 前綴外。例如，對 yiisoft/yii2-imagine 擴展來說，我們用 yii\imagine 作為它的類的命名空間。

不要使用 yii、yii2 或者 yiisoft 作為你的 vendor 名。這些名稱已由 Yii 內核代碼預留使用了。

類的自舉引導

有時候，你可能想讓你的擴展在應用的自舉過程中執(zhí)行一些代碼。例如，你的擴展可能想響應應用的 beginRequest 事件，做一些環(huán)境的設置工作。雖然你可以指導擴展的使用者顯式地將你的擴展中的事件句柄附加（綁定）到 beginRequest 事件，但是更好的方法是自動完成。

為實現該目標，你可以創(chuàng)建一個所謂 bootstrapping class （自舉類）實現 [[yii\base\BootstrapInterface]] 接口。例如，

namespace myname\mywidget;

use yii\base\BootstrapInterface;
use yii\base\Application;

class MyBootstrapClass implements BootstrapInterface
{
    public function bootstrap($app)
    {
        $app->on(Application::EVENT_BEFORE_REQUEST, function () {
             // do something here
        });
    }
}

You then list this class in the composer.json file of your extension like follows,

然后你將這個類在 composer.json 文件中列出來，如下所示，

{
    // ...

    "extra": {
        "bootstrap": "myname\\mywidget\\MyBootstrapClass"
    }
}

When the extension is installed in an application, 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. 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.

If your extension needs to create specific DB tables or make changes to DB schema, you should

provide migrations to manipulate DB schema, rather than using plain SQL files;
try to make the migrations applicable to different DBMS;
avoid using Active Record in the migrations.

Using Assets

If your extension is a widget or a module, chances are that it may require some assets to work. For example, a module may display some pages which contain 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:

ask users of the extension to manually copy the asset files to a specific Web-accessible folder;
declare an asset bundle and rely on the asset publishing mechanism to automatically copy the files listed in the asset bundle to a Web-accessible folder.

We recommend you use the second approach so that your extension can be more easily used by other people. Please refer to the Assets section for more details about how to work with assets in general.

Internationalization and Localization

Your extension may be used by applications supporting different languages! Therefore, if your extension displays content to end users, you should try to internationalize and localize it. In particular,

If the extension displays messages intended for end users, the messages should be wrapped into Yii::t() so that they can be translated. Messages meant for developers (such as internal exception messages) do not need to be translated.
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 section.

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 section.

Versioning

You should give each release of your extension a version number (e.g. 1.0.1). We recommend you follow the semantic versioning 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. 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. We recommend you write it in 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 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 to learn how to document your code.

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.

Info: While not a requirement, we suggest your extension adhere to certain coding styles. You may refer to the 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 and can be easily installed as described in the Using Extensions subsection.

yiisoft/yii2-apidoc: provides an extensible and high-performance API documentation generator. It is also used to generate the core framework API documentation.
yiisoft/yii2-authclient: provides a set of commonly used auth clients, such as Facebook OAuth2 client, GitHub OAuth2 client.
yiisoft/yii2-bootstrap: provides a set of widgets that encapsulate the Bootstrap components and plugins.
yiisoft/yii2-codeception: provides testing support based on Codeception.
yiisoft/yii2-debug: provides debugging support for Yii applications. When this extension is used, a debugger toolbar will appear at the bottom of every page. The extension also provides a set of standalone pages to display more detailed debug information.
yiisoft/yii2-elasticsearch: provides the support for using Elasticsearch. It includes basic querying/search support and also implements the Active Record pattern that allows you to store active records in Elasticsearch.
yiisoft/yii2-faker: provides the support for using Faker to generate fake data for you.
yiisoft/yii2-gii: provides a Web-based code generator that is highly extensible and can be used to quickly generate models, forms, modules, CRUD, etc.
yiisoft/yii2-imagine: provides commonly used image manipulation functions based on Imagine.
yiisoft/yii2-jui: provides a set of widgets that encapsulate the JQuery UI interactions and widgets.
yiisoft/yii2-mongodb: provides the support for using MongoDB. It includes features such as basic query, Active Record, migrations, caching, code generation, etc.
yiisoft/yii2-redis: provides the support for using redis. It includes features such as basic query, Active Record, caching, etc.
yiisoft/yii2-smarty: provides a template engine based on Smarty.
yiisoft/yii2-sphinx: provides the support for using Sphinx. It includes features such as basic query, Active Record, code generation, etc.
yiisoft/yii2-swiftmailer: provides email sending features based on swiftmailer.
yiisoft/yii2-twig: provides a template engine based on Twig.

當這個擴展安裝到應用后，Yii 將在每一個請求的自舉過程中自動實例化自舉類并調用其 [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] 方法。

操作數據庫

你的擴展可能要存取數據庫。不要假設使用你的擴展的應用總是用 Yii::$db 作為數據庫連接。你應當在需要訪問數據庫的類中申明一個 db 屬性。這個屬性允許你的擴展的用戶可定制你的擴展使用哪個 DB 連接。例如，你可以參考 [[yii\caching\DbCache]] 類看一下它是如何申明和使用 db 屬性的。

如果你的擴展需要創(chuàng)建特定的數據庫表，或者修改數據庫結構，你應當

提供數據遷移來操作數據庫的結構修改，而不是使用SQL文本文件；
盡量使遷移文件適用于不同的 DBMS；
在遷移文件中避免使用 Active Record。

使用 Assets

如果你的擴展是掛件或者模塊類型，它有可能需要使用一些 assets 。例如，一個模塊可能要顯示一些包含圖片，JavaScript 和 CSS 的頁面。因為擴展的文件都是放在同一個目錄之下，安裝之后 Web 無法讀取，你有兩個選擇使得這些 asset 文件目錄可以通過 Web 讀取：

讓擴展的用戶手動將這些 asset 文件拷貝到特定的 Web 可以讀取的文件夾；
申明一個 asset bundle 并依靠 asset 發(fā)布機制自動將這些文件（asset bundle 中列出的文件）拷貝到 Web 可讀的文件夾。

我們推薦你使用第二種方法，以便其他人能更容易使用你的擴展。更詳細的關于如何處理 assets ，請參照 Assets 章節(jié)。

國際化和本地化

你的擴展可能會在支持不同語言的應用中使用！因此，如果你的擴展要顯示內容給終端用戶，你應當試著實現國際化和本地化，特別地，

如果擴展為終端用戶顯示信息，這些信息應該用 Yii::t() 包裝起來，以便可以進行翻譯。只給開發(fā)者參考的信息（如內部異常信息）不需要做翻譯。
如果擴展顯示數字、日期等，你應該用 [[yii\i18n\Formatter]] 中適當的格式化規(guī)則做格式化處理。

更詳細的信息，請參照 Internationalization 章節(jié)。

測試

你一定想讓你的擴展可以無暇地運行而不會給其他人帶來問題和麻煩。為達到這個目的，你應當在公開發(fā)布前做測試。

推薦你創(chuàng)建測試用例，做全面覆蓋的測試你的擴展，而不只是依賴于手動測試。每次發(fā)布新版本前，你只要簡單地運行這些測試用例確保一切完好。Yii 提供了測試支持，使你更容易寫單元測試、驗收測試和功能測試。詳情請參照 Testing 章節(jié)。

版本控制

你應該為每一個擴展定一個版本號（如 1.0.1）。我們推薦你命名版本號時參照semantic versioning 決定用什么樣的版本號。

發(fā)布

為使其他人知道你的擴展，你應該公開發(fā)布。

如果你首次發(fā)布一個擴展，你應該在 Composer 代碼庫中注冊它，例如 Packagist。之后，你所需要做的僅僅是在版本管理庫中創(chuàng)建一個 tag （如v1.0.1），然后通知 Composer 代碼庫。其他人就能查找到這個新的發(fā)布了，并可通過 Composer 代碼庫安裝和更新該擴展。

在發(fā)布你的擴展時，除了代碼文件，你還應該考慮包含如下內容幫助其他人了解和使用你的擴展：

根目錄下的 readme 文件：它描述你的擴展是干什么的以及如何安裝和使用。我們推薦你用 Markdown 的格式來寫并將文件命名為 readme.md。
根目錄下的修改日志文件：它列舉每個版本的發(fā)布做了哪些更改。該文件可以用 Markdown 根式編寫并命名為 changelog.md。
根目錄下的升級文件：它給出如何從其他就版本升級該擴展的指導。該文件可以用 Markdown 根式編寫并命名為 changelog.md。
入門指南、演示代碼、截屏圖示等：如果你的擴展提供了許多功能，在 readme 文件中不能完整描述時，就要用到這些文件。
API 文檔：你的代碼應當做好文檔，讓其他人更容易閱讀和理解。你可以參照 Object class file學習如何為你的代碼做文檔。

信息：你的代碼注釋可以寫成 Markdown 格式。yiisof


            上一篇：類自動加載（Autoloading）下一篇：入口腳本