摘要：運(yùn)行來安裝指定的擴(kuò)展。這更便于用戶辨別是否是的擴(kuò)展。當(dāng)用戶運(yùn)行安裝一個(gè)擴(kuò)展時(shí)，文件會(huì)被自動(dòng)更新使之包含新擴(kuò)展的信息。上述代碼表明該擴(kuò)展依賴于包。例如，上述的條目聲明將對(duì)應(yīng)于別名。為達(dá)到這個(gè)目的，你應(yīng)當(dāng)在公開發(fā)布前做測試。

擴(kuò)展是專門設(shè)計(jì)的在 Yii 應(yīng)用中隨時(shí)可拿來使用的， 并可重發(fā)布的軟件包。

例如， yiisoft/yii2-debug 擴(kuò)展在你的應(yīng)用的每個(gè)頁面底部添加一個(gè)方便用于調(diào)試的工具欄， 幫助你簡單地抓取頁面生成的情況。 你可以使用擴(kuò)展來加速你的開發(fā)過程。

信息：本文中我們使用的術(shù)語 "擴(kuò)展" 特指 Yii 軟件包。而用術(shù)語 "軟件包" 和 "庫" 指代非 Yii 專用的通常意義上的軟件包。

使用擴(kuò)展要使用擴(kuò)展，你要先安裝它。大多數(shù)擴(kuò)展以 Composer 軟件包的形式發(fā)布， 這樣的擴(kuò)展可采取下述兩個(gè)步驟來安裝：

修改你的應(yīng)用的 composer.json 文件，指明你要安裝的是哪個(gè)擴(kuò)展 （Composer 軟件包）。

運(yùn)行 composer install 來安裝指定的擴(kuò)展。

注意如果你還沒有安裝 Composer ，你需要先安裝。

默認(rèn)情況，Composer安裝的是在 Packagist 中 注冊(cè)的軟件包 - 最大的開源 Composer 代碼庫。你可以在 Packageist 中查找擴(kuò)展。

你也可以 創(chuàng)建你自己的代碼庫 然后配置 Composer 來使用它。 如果是在開發(fā)私有的擴(kuò)展，并且想只在你的其他工程中共享時(shí)，這樣做是很有用的。

通過 Composer 安裝的擴(kuò)展會(huì)存放在 BasePath/vendor 目錄下，這里的 BasePath 指你的應(yīng)用的 base path。因?yàn)?Composer 還是一個(gè)依賴管理器，當(dāng)它安裝一個(gè)包時(shí)， 也將安裝這個(gè)包所依賴的所有軟件包。

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

{
    // ...
    "require": {
        // ... other dependencies
        "yiisoft/yii2-imagine": "*"
    }
}

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

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

現(xiàn)在你可以使用安裝好的擴(kuò)展了，好比是應(yīng)用的一部分。

如下示例展示了如何使用 yiisoft/yii2-imagine 擴(kuò)展 提供的yiiimagineImage 類：

use Yii;
use yiiimagineImage;

// 生成一個(gè)縮略圖
Image::thumbnail("@webroot/img/test-image.jpg", 120, 120)
    ->save(Yii::getAlias("@runtime/thumb-test-image.jpg"), ["quality" => 50]);

信息： 擴(kuò)展類由 Yii class autoloader 自動(dòng)加載。

在極少情況下，你可能需要手動(dòng)安裝一部分或者全部擴(kuò)展，而不是依賴 Composer。 想做到這一點(diǎn)，你應(yīng)當(dāng)：

下載擴(kuò)展壓縮文件，解壓到 vendor 目錄。

如果有，則安裝擴(kuò)展提供的自動(dòng)加載器。

按指導(dǎo)說明下載和安裝所有依賴的擴(kuò)展。

如果擴(kuò)展沒有提供類的自動(dòng)加載器，但也遵循了 PSR-4 standard 標(biāo)準(zhǔn)，那么你可以使用 Yii 提供的類自動(dòng)加載器來加載擴(kuò)展類。 你需要做的僅僅是為擴(kuò)展的根目錄聲明一個(gè) root alias。

例如，假設(shè)在 vendor/mycompany/myext 目錄中安裝了一個(gè)擴(kuò)展，并且擴(kuò)展類的命名空間為 myext ， 那么你可以在應(yīng)用配置文件中包含如下代碼：

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

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

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

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

為你的擴(kuò)展建一個(gè)工程，并將它存放在版本控制代碼庫中，例如 github.com 。 擴(kuò)展的開發(fā)和維護(hù)都應(yīng)該在這個(gè)代碼庫中進(jìn)行。

在工程的根目錄下，建一個(gè) Composer 所需的名為 composer.json 的文件。 詳情請(qǐng)參考后面的章節(jié)。

在一個(gè) Composer 代碼庫中注冊(cè)你的擴(kuò)展，比如在 Packagist 中，以便其他 用戶能找到以及用 Composer 安裝你的擴(kuò)展。

composer.json
每個(gè) Composer 軟件包在根目錄都必須有一個(gè) composer.json 文件。該文件包含軟件包的元數(shù)據(jù)。

你可以在 Composer手冊(cè) 中找到完整關(guān)于該文件的規(guī)格。 以下例子展示了 yiisoft/yii2-imagine 擴(kuò)展的 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": {
            "yiiimagine": ""
        }
    }
}

每個(gè) Composer 軟件包都應(yīng)當(dāng)有一個(gè)唯一的包名以便能從其他的軟件包中識(shí)別出來。 包名的格式為 vendorName/projectName 。

例如在包名 yiisoft/yii2-imagine 中，vendor 名和 project 名分別是 yiisoft 和 yii2-imagine 。

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

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

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

當(dāng)用戶運(yùn)行 composer install 安裝一個(gè)擴(kuò)展時(shí)， vendor/yiisoft/extensions.php 文件會(huì)被自動(dòng)更新使之包含新擴(kuò)展的信息。從該文件中， Yii 應(yīng)用程序就能知道安裝了 哪些擴(kuò)展 (這些信息可通過 yiibaseApplication::extensions 訪問)。

你的擴(kuò)展依賴于 Yii （理所當(dāng)然）。因此你應(yīng)當(dāng)在 composer.json 文件中列出它 (yiisoft/yii2)。

如果你的擴(kuò)展還依賴其他的擴(kuò)展或者是第三方庫，你也要一并列出來。 確定你也為每一個(gè)依賴的包列出了適當(dāng)?shù)陌姹炯s束條件 (比如 1.*, @stable) 。 當(dāng)你發(fā)布一個(gè)穩(wěn)定版本時(shí)，你所依賴的包也應(yīng)當(dāng)使用穩(wěn)定版本。

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

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

上述代碼表明該擴(kuò)展依賴于 jquery Bower 包。

一般來說，你可以在 composer.json 中用 bower-asset/PackageName 指定 Bower 包，用 npm-asset/PackageName 指定 NPM 包。

當(dāng) Compower 安裝 Bower 和 NPM 軟件包時(shí)，包的內(nèi)容默認(rèn)會(huì)分別安裝到@vendor/bower/PackageName 和 @vendor/npm/Packages 下。

這兩個(gè)目錄還可以分別用 @bower/PackageName 和@npm/PackageName 別名指向。

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

{
    // ....

    "autoload": {
        "psr-4": {
            "yiiimagine": ""
        }
    }
}

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

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

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

為避免沖突以及使你的擴(kuò)展中的類能被自動(dòng)加載，你的類應(yīng)當(dāng)使用命名空間， 并使類的命名符合 PSR-4 standard 或者 PSR-0 standard 標(biāo)準(zhǔn)。

你的類的命名空間應(yīng)以 vendorNameextensionName 起始，其中 extensionName 和項(xiàng)目名相同，除了它沒有 yii2- 前綴外。例如，對(duì) yiisoft/yii2-imagine 擴(kuò)展 來說，我們用 yiiimagine 作為它的類的命名空間。

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

有時(shí)候，你可能想讓你的擴(kuò)展在應(yīng)用的 自舉過程 中執(zhí)行一些代碼。

例如，你的擴(kuò)展可能想響應(yīng)應(yīng)用的 beginRequest 事件，做一些環(huán)境的設(shè)置工作。 雖然你可以指導(dǎo)擴(kuò)展的使用者顯式地將你的擴(kuò)展中的事件句柄附加（綁定）到 beginRequest 事件， 但是更好的方法是自動(dòng)完成。

為實(shí)現(xiàn)該目標(biāo)，你可以創(chuàng)建一個(gè)所謂 bootstrapping class （自舉類）實(shí)現(xiàn) yiibaseBootstrapInterface 接口。

例如：

namespace mynamemywidget;

use yiiaseBootstrapInterface;
use yiiaseApplication;

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

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

{
    // ...

    "extra": {
        "bootstrap": "mynamemywidgetMyBootstrapClass"
    }
}

當(dāng)這個(gè)擴(kuò)展安裝到應(yīng)用后，Yii 將在每一個(gè)請(qǐng)求的自舉過程中 自動(dòng)實(shí)例化自舉類并調(diào)用其 yiibaseBootstrapInterface::bootstrap() 方法。

你的擴(kuò)展可能要存取數(shù)據(jù)庫。不要假設(shè)使用你的擴(kuò)展的應(yīng)用總是用 Yii::$db 作為數(shù)據(jù)庫連接。你應(yīng)當(dāng)在需要訪問數(shù)據(jù)庫的類中申明一個(gè) db 屬性。 這個(gè)屬性允許你的擴(kuò)展的用戶可定制你的擴(kuò)展使用哪個(gè) DB 連接。例如， 你可以參考 yiicachingDbCache 類看一下它是如何申明和使用 db 屬性的。

如果你的擴(kuò)展需要?jiǎng)?chuàng)建特定的數(shù)據(jù)庫表，或者修改數(shù)據(jù)庫結(jié)構(gòu)，你應(yīng)當(dāng)

提供 數(shù)據(jù)遷移 來操作數(shù)據(jù)庫的結(jié)構(gòu)修改，而不是使用SQL文本文件；

盡量使遷移文件適用于不同的 DBMS；

在遷移文件中避免使用 Active Record。

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

讓擴(kuò)展的用戶手動(dòng)將這些 asset 文件拷貝到特定的 Web 可以讀取的文件夾；

申明一個(gè) asset bundle 并依靠 asset 發(fā)布機(jī)制自動(dòng)將這些文件（asset bundle 中列出的文件） 拷貝到 Web 可讀的文件夾。

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

你的擴(kuò)展可能會(huì)在支持不同語言的應(yīng)用中使用！因此，如果你的擴(kuò)展要顯示內(nèi)容給終端用戶， 你應(yīng)當(dāng)試著實(shí)現(xiàn) 國際化和本地化，特別地，

如果擴(kuò)展為終端用戶顯示信息，這些信息應(yīng)該用 Yii::t() 包裝起來，以便可以進(jìn)行翻譯。 只給開發(fā)者參考的信息（如內(nèi)部異常信息）不需要做翻譯。

如果擴(kuò)展顯示數(shù)字、日期等，你應(yīng)該用 yiii18nFormatter 中適當(dāng)?shù)母袷交?guī)則做格式化處理。

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

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

你應(yīng)該為每一個(gè)擴(kuò)展定一個(gè)版本號(hào)（如 1.0.1）。我們推薦你命名版本號(hào)時(shí)參照 semantic versioning 決定用什么樣的版本號(hào)。

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

如果你首次發(fā)布一個(gè)擴(kuò)展，你應(yīng)該在 Composer 代碼庫中注冊(cè)它，例如 Packagist。之后，你所需要做的僅僅是在 版本管理庫中創(chuàng)建一個(gè) tag （如v1.0.1），然后通知 Composer 代碼庫。

其他人就能查找到這個(gè)新的發(fā)布了，并可通過 Composer 代碼庫安裝和更新該擴(kuò)展。

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

根目錄下的 readme 文件：它描述你的擴(kuò)展是干什么的以及如何安裝和使用。 我們推薦你用 Markdown 的格式 來寫并將文件命名為readme.md。

根目錄下的修改日志文件：它列舉每個(gè)版本的發(fā)布做了哪些更改。該文件可以用 Markdown 根式 編寫并命名為 changelog.md。

根目錄下的升級(jí)文件：它給出如何從其他就版本升級(jí)該擴(kuò)展的指導(dǎo)。該文件可以用 Markdown 根式 編寫并命名為 changelog.md。

入門指南、演示代碼、截屏圖示等：如果你的擴(kuò)展提供了許多功能，在 readme 文件中不能完整 描述時(shí)，就要用到這些文件。

API 文檔：你的代碼應(yīng)當(dāng)做好文檔，讓其他人更容易閱讀和理解。 你可以參照 Object class file 學(xué)習(xí)如何為你的代碼做文檔。

信息：你的代碼注釋可以寫成 Markdown 格式。yiisoft/yii2-apidoc 擴(kuò)展為你提供了一個(gè)從你的 代碼注釋生成漂亮的 API 文檔。

信息：雖然不做要求，我們還是建議你的擴(kuò)展遵循某個(gè)編碼規(guī)范。 你可以參照 core framework code style。

Yii 提供了下列核心擴(kuò)展，由 Yii 開發(fā)團(tuán)隊(duì)開發(fā)和維護(hù)。這些擴(kuò)展全都在 Packagist 中注冊(cè)，并像 Using Extensions 章節(jié)描述 的那樣容易安裝。

yiisoft/yii2-apidoc: 提供了一個(gè)可擴(kuò)展的、高效的 API 文檔生成器。核心框架的 API 文檔也是用它生成的。

yiisoft/yii2-authclient: 提供了一套常用的認(rèn)證客戶端，例如 Facebook OAuth2 客戶端、GitHub OAuth2 客戶端。

yiisoft/yii2-bootstrap: 提供了一套掛件，封裝了 Bootstrap 的組件和插件。

yiisoft/yii2-codeception: 提供了基于 Codeception 的測試支持。

yiisoft/yii2-debug: 提供了對(duì) Yii 應(yīng)用的調(diào)試支持。當(dāng)使用該擴(kuò)展是， 在每個(gè)頁面的底部將顯示一個(gè)調(diào)試工具條。 該擴(kuò)展還提供了一個(gè)獨(dú)立的頁面，以顯示更詳細(xì)的調(diào)試信息。

yiisoft/yii2-elasticsearch: 提供對(duì) Elasticsearch 的使用支持。它包含基本的查詢/搜索支持， 并實(shí)現(xiàn)了 Active Record 模式讓你可以將活動(dòng)記錄 存儲(chǔ)在 Elasticsearch 中。

yiisoft/yii2-faker: 提供了使用 Faker 的支持，為你生成模擬數(shù)據(jù)。

yiisoft/yii2-gii: 提供了一個(gè)基于頁面的代碼生成器，具有高可擴(kuò)展性，并能用來快速生成模型、 表單、模塊、CRUD等。

yiisoft/yii2-imagine: 提供了基于 Imagine 的常用圖像處理功能。

yiisoft/yii2-jui: 提供了一套封裝 JQuery UI 的掛件以及它們的交互。

yiisoft/yii2-mongodb: 提供了對(duì) MongoDB 的使用支持。它包含基本 的查詢、活動(dòng)記錄、數(shù)據(jù)遷移、緩存、代碼生成等特性。

yiisoft/yii2-redis: 提供了對(duì) redis 的使用支持。它包含基本的 查詢、活動(dòng)記錄、緩存等特性。

yiisoft/yii2-smarty: 提供了一個(gè)基于 Smarty 的模板引擎。

yiisoft/yii2-sphinx: 提供了對(duì) Sphinx 的使用支持。它包含基本的 查詢、活動(dòng)記錄、代碼生成等特性。

yiisoft/yii2-swiftmailer: 提供了基于 swiftmailer 的郵件發(fā)送功能。

yiisoft/yii2-twig: 提供了一個(gè)基于 Twig 的模板引擎。