擴展

擴展是專門設計的在 Yii 應用中隨時可拿來使用的， 并可重發(fā)布的軟件包。例如，?yiisoft/yii2-debug?擴展在你的應用的每個頁面底部添加一個方便用于調(diào)試的工具欄， 幫助你簡單地抓取頁面生成的情況。 你可以使用擴展來加速你的開發(fā)過程。

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

使用擴展

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

1. 修改你的應用的?composer.json?文件，指明你要安裝的是哪個擴展 （Composer 軟件包）。
2. 運行?composer install?來安裝指定的擴展。

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

默認情況，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": "*"
    }
}

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

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

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

use Yii;
use yii\imagine\Image;

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

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

手動安裝擴展

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

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

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

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

創(chuàng)建擴展

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

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

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

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

composer.json

每個 Composer 軟件包在根目錄都必須有一個?composer.json?文件。該文件包含軟件包的元數(shù)據(jù)。 你可以在?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\\": ""
        }
    }
}

包名

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

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

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

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

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

類的自動加載

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

{
    // ....

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

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

當擴展安裝到應用中后，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 內(nèi)核代碼預留使用了。

類的自舉引導

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

為實現(xiàn)該目標，你可以創(chuàng)建一個所謂?bootstrapping class?（自舉類）實現(xiàn) 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
        });
    }
}

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

{
    // ...

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

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

操作數(shù)據(jù)庫

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

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

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

使用 Assets

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

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

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

國際化和本地化

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

• 如果擴展為終端用戶顯示信息，這些信息應該用?Yii::t()?包裝起來，以便可以進行翻譯。 只給開發(fā)者參考的信息（如內(nèi)部異常信息）不需要做翻譯。
• 如果擴展顯示數(shù)字、日期等，你應該用 yii\i18n\Formatter 中適當?shù)母袷交?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ā)布你的擴展時，除了代碼文件，你還應該考慮包含如下內(nèi)容 幫助其他人了解和使用你的擴展：

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

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

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

核心擴展

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

• yiisoft/yii2-apidoc: 提供了一個可擴展的、高效的 API 文檔生成器。核心框架的 API 文檔也是用它生成的。
• yiisoft/yii2-authclient: 提供了一套常用的認證客戶端，例如 Facebook OAuth2 客戶端、GitHub OAuth2 客戶端。
• yiisoft/yii2-bootstrap: 提供了一套掛件，封裝了?Bootstrap?的組件和插件。
• yiisoft/yii2-codeception: 提供了基于?Codeception?的測試支持。
• yiisoft/yii2-debug: 提供了對 Yii 應用的調(diào)試支持。當使用該擴展是， 在每個頁面的底部將顯示一個調(diào)試工具條。 該擴展還提供了一個獨立的頁面，以顯示更詳細的調(diào)試信息。
• yiisoft/yii2-elasticsearch: 提供對?Elasticsearch?的使用支持。它包含基本的查詢/搜索支持， 并實現(xiàn)了?Active Record?模式讓你可以將活動記錄 存儲在 Elasticsearch 中。
• yiisoft/yii2-faker: 提供了使用?Faker?的支持，為你生成模擬數(shù)據(jù)。
• yiisoft/yii2-gii: 提供了一個基于頁面的代碼生成器，具有高可擴展性，并能用來快速生成模型、 表單、模塊、CRUD等。
• yiisoft/yii2-imagine: 提供了基于?Imagine?的常用圖像處理功能。
• yiisoft/yii2-jui: 提供了一套封裝?JQuery UI?的掛件以及它們的交互。
• yiisoft/yii2-mongodb: 提供了對?MongoDB?的使用支持。它包含基本 的查詢、活動記錄、數(shù)據(jù)遷移、緩存、代碼生成等特性。
• yiisoft/yii2-redis: 提供了對?redis?的使用支持。它包含基本的 查詢、活動記錄、緩存等特性。
• yiisoft/yii2-smarty: 提供了一個基于?Smarty?的模板引擎。
• yiisoft/yii2-sphinx: 提供了對?Sphinx?的使用支持。它包含基本的 查詢、活動記錄、代碼生成等特性。
• yiisoft/yii2-swiftmailer: 提供了基于?swiftmailer?的郵件發(fā)送功能。
• yiisoft/yii2-twig: 提供了一個基于?Twig?的模板引擎。