擴(kuò)展（Extensions）

2018-02-24 15:40 更新

擴(kuò)展

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

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

使用擴(kuò)展

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

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

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

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

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

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

{
    // ...

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

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

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

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

現(xiàn)在你可以使用安裝好的擴(kuò)展了，好比是應(yīng)用的一部分。如下示例展示了如何使用?yiisoft/yii2-imagine?擴(kuò)展 提供的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]);

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

手動安裝擴(kuò)展

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

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

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

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

創(chuàng)建擴(kuò)展

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

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

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

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

composer.json

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

包名

每個 Composer 軟件包都應(yīng)當(dāng)有一個唯一的包名以便能從其他的軟件包中識別出來。 包名的格式為?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?類型很重要，以便安裝的時候 能被識別出是一個 Yii 擴(kuò)展。

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

依賴

你的擴(kuò)展依賴于 Yii （理所當(dāng)然）。因此你應(yīng)當(dāng)在?composer.json?文件中列出它 (yiisoft/yii2)。如果你的擴(kuò)展還依賴其他的擴(kuò)展或者是第三方庫，你也要一并列出來。 確定你也為每一個依賴的包列出了適當(dāng)?shù)陌姹炯s束條件 (比如?1.*,?@stable) 。 當(dāng)你發(fā)布一個穩(wěn)定版本時，你所依賴的包也應(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 軟件包時，包的內(nèi)容默認(rèn)會分別安裝到@vendor/bower/PackageName?和?@vendor/npm/Packages?下。這兩個目錄還可以分別用?@bower/PackageName?和@npm/PackageName?別名指向。

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

類的自動加載

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

{
    // ....

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

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

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

推薦的做法

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

命名空間

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

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

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

類的自舉引導(dǎo)

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

為實現(xiàn)該目標(biāo)，你可以創(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"
    }
}

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

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

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

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

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

使用 Assets

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

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

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

國際化和本地化

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

  • 如果擴(kuò)展為終端用戶顯示信息，這些信息應(yīng)該用?Yii::t()?包裝起來，以便可以進(jìn)行翻譯。 只給開發(fā)者參考的信息（如內(nèi)部異常信息）不需要做翻譯。
  • 如果擴(kuò)展顯示數(shù)字、日期等，你應(yīng)該用 yii\i18n\Formatter 中適當(dāng)?shù)母袷交?guī)則做格式化處理。

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

測試

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

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

版本控制

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

發(fā)布

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

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

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

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

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

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

核心擴(kuò)展

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

以上內(nèi)容是否對您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號