0 追蹤者

擴展

擴展是專為 Yii 應用程式設計的可重新發佈軟體套件，提供隨即可用的功能。例如，yiisoft/yii2-debug 擴展在您應用程式的每個頁面底部新增一個方便的偵錯工具列，以協助您更輕鬆地掌握頁面的產生方式。您可以使用擴展來加速您的開發流程。您也可以將您的程式碼打包為擴展，與其他人分享您的出色成果。

資訊：我們使用「擴展」一詞來指稱 Yii 專用的軟體套件。對於不需 Yii 即可使用的一般用途軟體套件，我們將使用「套件」或「程式庫」一詞來指稱它們。

使用擴展

若要使用擴展，您需要先安裝它。大多數擴展都以 Composer 套件的形式發佈，可以透過以下兩個簡單的步驟安裝

  1. 修改您應用程式的 composer.json 檔案，並指定您要安裝哪些擴展（Composer 套件）。
  2. 執行 composer install 以安裝指定的擴展。

請注意，如果您沒有 Composer，您可能需要安裝它。

預設情況下，Composer 安裝在 Packagist 上註冊的套件 - Packagist 是最大的開源 Composer 套件儲存庫。您可以在 Packagist 上尋找擴展。您也可以建立您自己的儲存庫並設定 Composer 使用它。如果您正在開發只想在您的專案內共享的私有擴展，這會很有用。

Composer 安裝的擴展會儲存在 BasePath/vendor 目錄中，其中 BasePath 指的是應用程式的 基礎路徑。由於 Composer 是相依性管理器，因此當它安裝套件時，也會安裝其所有相依套件。

例如，若要安裝 yiisoft/yii2-imagine 擴展，請修改您的 composer.json，如下所示

{
    // ...

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

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

安裝後，您應該會在 BasePath/vendor 下看到目錄 yiisoft/yii2-imagine。您也應該看到另一個目錄 imagine/imagine，其中包含已安裝的相依套件。

資訊：yiisoft/yii2-imagine 是由 Yii 開發團隊開發和維護的核心擴展。所有核心擴展都託管在 Packagist 上，並命名為 yiisoft/yii2-xyz，其中 xyz 因不同的擴展而異。

現在您可以使用已安裝的擴展，就像它們是您應用程式的一部分一樣。以下範例示範如何使用 yiisoft/yii2-imagine 擴展提供的 yii\imagine\Image 類別

use Yii;
use yii\imagine\Image;

// generate a thumbnail image
Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
    ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);

資訊：擴展類別由 Yii 類別自動載入器自動載入。

手動安裝擴展

在某些罕見的情況下，您可能想要手動安裝部分或全部擴展，而不是依賴 Composer。若要這樣做，您應該

  1. 下載擴展封存檔案並將其解壓縮到 vendor 目錄中。
  2. 安裝擴展提供的類別自動載入器（如果有的話）。
  3. 下載並安裝所有相依的擴展，如指示所示。

如果擴展沒有類別自動載入器，但遵循 PSR-4 標準，您可以使用 Yii 提供的類別自動載入器來自動載入擴展類別。您只需要為擴展根目錄宣告一個根別名。例如，假設您已將擴展安裝在目錄 vendor/mycompany/myext 中，且擴展類別位於 myext 命名空間下，則您可以將以下程式碼包含在您的應用程式配置中

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

建立擴展

當您覺得需要與其他人分享您的出色程式碼時，您可以考慮建立擴展。擴展可以包含您喜歡的任何程式碼，例如輔助類別、小工具、模組等。

建議您以 Composer 套件的形式建立擴展，以便其他使用者可以更輕鬆地安裝和使用它，如上一個小節所述。

以下是您可以遵循的建立擴展作為 Composer 套件的基本步驟。

  1. 為您的擴展建立一個專案，並將其託管在 VCS 儲存庫上，例如 github.com。擴展的開發和維護工作應在此儲存庫上完成。
  2. 在專案的根目錄下，建立一個名為 composer.json 的檔案，這是 Composer 所要求的。請參閱下一個小節以取得更多詳細資訊。
  3. 向 Composer 儲存庫（例如 Packagist）註冊您的擴展，以便其他使用者可以使用 Composer 找到並安裝您的擴展。

composer.json

每個 Composer 套件都必須在其根目錄中包含一個 composer.json 檔案。該檔案包含有關套件的中繼資料。您可以在 Composer 手冊中找到有關此檔案的完整規格。以下範例顯示了 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": "https://forum.yiiframework.com/",
        "wiki": "https://yii.dev.org.tw/wiki/",
        "irc": "ircs://irc.libera.chat:6697/yii",
        "source": "https://github.com/yiisoft/yii2"
    },
    "authors": [
        {
            "name": "Antonio Ramirez",
            "email": "amigo.cobos@gmail.com"
        }
    ],

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

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

套件名稱

每個 Composer 套件都應該有一個套件名稱，以在所有其他套件中唯一識別該套件。套件名稱的格式為 vendorName/projectName。例如，在套件名稱 yiisoft/yii2-imagine 中，供應商名稱和專案名稱分別為 yiisoft 和 yii2-imagine。

請勿使用 yiisoft 作為您的供應商名稱，因為它保留供 Yii 核心程式碼使用。

我們建議您為代表 Yii 2 擴展的套件在專案名稱前加上 yii2- 前綴，例如 myname/yii2-mywidget。這將允許使用者更輕鬆地判斷套件是否為 Yii 2 擴展。

套件類型

重要的是，您將擴展的套件類型指定為 yii2-extension，以便在安裝時可以將該套件識別為 Yii 擴展。

當使用者執行 composer install 安裝擴展時，檔案 vendor/yiisoft/extensions.php 將自動更新，以包含有關新擴展的資訊。從此檔案中，Yii 應用程式可以知道安裝了哪些擴展（資訊可以透過 yii\base\Application::$extensions 存取）。

相依性

您的擴展相依於 Yii（當然）。因此，您應該在 composer.json 中的 require 條目中列出它 (yiisoft/yii2)。如果您的擴展也相依於其他擴展或第三方程式庫，您也應該將它們列出。請確保您也為每個相依套件列出適當的版本約束（例如 1.*、@stable）。當您的擴展以穩定版本發佈時，請使用穩定的相依性。

大多數 JavaScript/CSS 套件都使用 Bower 和/或 NPM 而非 Composer 進行管理。Yii 使用 Composer asset plugin 來啟用透過 Composer 管理這些類型的套件。如果您的擴展相依於 Bower 套件，您可以簡單地在 composer.json 中列出相依性，如下所示

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

上面的程式碼表示擴展相依於 jquery Bower 套件。一般來說，您可以使用 bower-asset/PackageName 在 composer.json 中引用 Bower 套件，並使用 npm-asset/PackageName 引用 NPM 套件。當 Composer 安裝 Bower 或 NPM 套件時，預設情況下，套件內容將安裝在 @vendor/bower/PackageName 和 @vendor/npm/Packages 目錄下。這兩個目錄也可以使用較短的別名 @bower/PackageName 和 @npm/PackageName 引用。

有關資源管理的更多詳細資訊，請參閱資源章節。

類別自動載入

為了讓您的類別可以由 Yii 類別自動載入器或 Composer 類別自動載入器自動載入，您應該在 composer.json 檔案中指定 autoload 條目，如下所示

{
    // ....

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

您可以列出一個或多個根命名空間及其對應的檔案路徑。

當擴展安裝在應用程式中時，Yii 將為每個列出的根命名空間建立一個 別名，該別名指向與命名空間對應的目錄。例如，上面的 autoload 宣告將對應於名為 @yii/imagine 的別名。

由於擴展旨在供其他人使用，因此您通常需要在開發期間付出額外的努力。以下我們介紹一些建立高品質擴展的常見和建議實務。

命名空間

為了避免名稱衝突並使您的擴展中的類別可自動載入，您應該使用命名空間並依照 PSR-4 標準 或 PSR-0 標準命名您的擴展中的類別。

您的類別命名空間應該以 vendorName\extensionName 開頭，其中 extensionName 類似於套件名稱中的專案名稱，只是它不應包含 yii2- 前綴。例如，對於 yiisoft/yii2-imagine 擴展，我們使用 yii\imagine 作為其類別的命名空間。

請勿使用 yii、yii2 或 yiisoft 作為您的供應商名稱。這些名稱保留供 Yii 核心程式碼使用。

啟動類別

有時，您可能希望您的擴展在應用程式的啟動流程階段執行一些程式碼。例如，您的擴展可能想要回應應用程式的 beginRequest 事件，以調整某些環境設定。雖然您可以指示擴展的使用者在擴展中明確地將您的事件處理常式附加到 beginRequest 事件，但更好的方法是自動執行此操作。

為了實現此目標，您可以透過實作 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 將自動實例化啟動類別，並在每次請求的啟動流程期間呼叫其 bootstrap() 方法。

使用資料庫

您的擴展可能需要存取資料庫。請勿假設使用您擴展的應用程式將始終使用 Yii::$db 作為 DB 連線。相反地，您應該為需要 DB 存取的類別宣告一個 db 屬性。該屬性將允許您的擴展的使用者自訂他們希望您的擴展使用的 DB 連線。作為一個範例，您可以參考 yii\caching\DbCache 類別，並查看它如何宣告和使用 db 屬性。

如果您的擴展需要建立特定的 DB 表格或變更 DB 結構描述，您應該

  • 提供遷移來操作 DB 結構描述，而不是使用純 SQL 檔案；
  • 嘗試使遷移適用於不同的 DBMS；
  • 避免在遷移中使用 Active Record。

使用資源

如果您的擴展是小工具或模組，則它很可能需要一些 資源才能運作。例如，模組可能會顯示一些包含影像、JavaScript 和 CSS 的頁面。由於擴展的檔案都位於同一個目錄下，該目錄在安裝到應用程式中時無法透過 Web 存取，因此您有兩個選擇可以使資源檔案直接透過 Web 存取

  • 要求擴展的使用者手動將資源檔案複製到特定的可透過 Web 存取的資料夾；
  • 宣告一個 資源包 並依靠資源發佈機制來自動將資源包中列出的檔案複製到可透過 Web 存取的資料夾。

我們建議您使用第二種方法，以便您的擴展可以更輕鬆地供其他人使用。請參閱資源章節，以取得有關如何一般性地使用資源的更多詳細資訊。

國際化與在地化

您的擴展可能會被支援不同語言的應用程式使用！因此，如果您的擴展向終端使用者顯示內容，您應該嘗試對其進行國際化和在地化。特別是，

  • 如果擴展顯示預期供終端使用者使用的訊息，則訊息應包裝在 Yii::t() 中，以便可以翻譯它們。預期供開發人員使用的訊息（例如內部例外訊息）不需要翻譯。
  • 如果擴展顯示數字、日期等，則應使用 yii\i18n\Formatter 以適當的格式化規則格式化它們。

有關更多詳細資訊，請參閱國際化章節。

測試

您希望您的擴展完美運行，而不會給其他人帶來問題。為了達到此目標，您應該在將擴展發佈到公眾之前對其進行測試。

建議您建立各種測試案例來涵蓋您的擴展程式碼，而不是依賴手動測試。每次在您發佈新版本的擴展之前，您都可以簡單地執行這些測試案例，以確保一切狀況良好。Yii 提供測試支援，可以協助您更輕鬆地編寫單元測試、驗收測試和功能測試。有關更多詳細資訊，請參閱測試章節。

版本控制

您應該為您的擴展的每個版本發佈一個版本號碼（例如 1.0.1）。我們建議您在決定應使用哪些版本號碼時，遵循語意化版本控制實務。

發佈

若要讓其他人知道您的擴展，您需要將其發佈到公眾。

如果是您第一次發佈擴展，您應該在 Composer 儲存庫（例如 Packagist）上註冊它。在那之後，您只需要在您的擴展的 VCS 儲存庫上建立一個發佈標籤（例如 v1.0.1），並將新版本發佈通知 Composer 儲存庫。然後，人們將能夠找到新版本，並透過 Composer 儲存庫安裝或更新擴展。

在您的擴展版本中，除了程式碼檔案之外，您也應該考慮包含以下內容，以協助其他人了解和使用您的擴展

  • 套件根目錄中的 readme 檔案：它描述了您的擴展的功能以及如何安裝和使用它。我們建議您以 Markdown 格式撰寫它，並將檔案命名為 readme.md。
  • 套件根目錄中的 changelog 檔案：它列出了每個版本中所做的變更。該檔案可以 Markdown 格式撰寫，並命名為 changelog.md。
  • 套件根目錄中的 upgrade 檔案：它提供了有關如何從舊版本擴展升級的說明。該檔案可以 Markdown 格式撰寫，並命名為 upgrade.md。
  • 教學課程、示範、螢幕截圖等：如果您的擴展提供了許多無法在 readme 檔案中完全涵蓋的功能，則需要這些內容。
  • API 文件：您的程式碼應妥善記錄，以允許其他人更輕鬆地閱讀和理解它。您可以參考 BaseObject 類別檔案，以了解如何記錄您的程式碼。

資訊：您的程式碼註解可以用 Markdown 格式撰寫。yiisoft/yii2-apidoc 擴展提供了一個工具，供您根據您的程式碼註解產生美觀的 API 文件。

資訊：雖然不是必需的，但我們建議您的擴展遵守某些程式碼樣式。您可以參考核心框架程式碼樣式。

核心擴展

Yii 提供了以下核心擴展（或 「官方擴展」），這些擴展由 Yii 開發團隊開發和維護。它們都在 Packagist 上註冊，並且可以輕鬆地按照使用擴展小節中的說明進行安裝。

以下官方擴展適用於 Yii 2.1 及更高版本。您不需要為 Yii 2.0 安裝它們，因為它們已包含在核心框架中。

資源
回到頂端
處理請求：請求處理概觀

發現錯字或您認為此頁面需要改進？
在 github 上編輯 !