套件系統

編輯此頁面

警告

在 Symfony 4.0 之前的版本中，建議使用套件來組織您自己的應用程式碼。現在已不再建議這樣做，套件應僅用於在多個應用程式之間共享程式碼和功能。

套件類似於其他軟體中的外掛程式，但功能更強大。Symfony 框架的核心功能是透過套件實作的（FrameworkBundle、SecurityBundle、DebugBundle 等）。它們也用於透過第三方套件在您的應用程式中新增功能。

應用程式中使用的套件必須在 config/bundles.php 檔案中針對每個環境啟用

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // config/bundles.php
return [
    // 'all' means that the bundle is enabled for any Symfony environment
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    // ...

    // this bundle is enabled only in 'dev'
    Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true],
    // ...

    // this bundle is enabled only in 'dev' and 'test', so you can't use it in 'prod'
    Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
    // ...
];
    

提示

在使用 Symfony Flex 的預設 Symfony 應用程式中，套件會在您安裝/移除它們時自動啟用/停用，因此您不需要查看或編輯此 bundles.php 檔案。

建立套件

本節建立並啟用一個新的套件，以展示只需幾個步驟即可完成。新的套件稱為 AcmeBlogBundle，其中 Acme 部分是一個範例名稱，應替換為代表您或您的組織的「供應商」名稱（例如，對於名為 Abc 的公司，可以使用 AbcBlogBundle）。

首先建立一個名為 AcmeBlogBundle 的新類別

        1
2
3
4
5
6
7
8
        // src/AcmeBlogBundle.php
namespace Acme\BlogBundle;

use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class AcmeBlogBundle extends AbstractBundle
{
}
    

警告

如果您的套件必須與先前的 Symfony 版本相容，則必須從 Bundle 擴展。

提示

AcmeBlogBundle 這個名稱遵循標準的套件命名慣例。您也可以選擇將套件名稱縮短為 BlogBundle，方法是將此類別命名為 BlogBundle（並將檔案命名為 BlogBundle.php）。

這個空的類別是建立新套件所需的唯一部分。雖然通常是空的，但這個類別功能強大，可用於自訂套件的行為。現在您已經建立套件，請啟用它

        1
2
3
4
5
        // config/bundles.php
return [
    // ...
    Acme\BlogBundle\AcmeBlogBundle::class => ['all' => true],
];
    

雖然它目前還沒有任何作用，但 AcmeBlogBundle 現在已準備好可以使用了。

套件目錄結構

套件的目錄結構旨在協助在所有 Symfony 套件之間保持程式碼一致性。它遵循一組慣例，但可以靈活調整。

assets/: 包含 Web 資源來源，例如 JavaScript 和 TypeScript 檔案、CSS 和 Sass 檔案，以及與套件相關但不在 public/ 中的圖片和其他資源（例如 Stimulus 控制器）。
config/: 存放組態，包括路由組態（例如 routes.php）。
public/: 包含 Web 資源（圖片、編譯後的 CSS 和 JavaScript 檔案等），並透過 assets:install 主控台命令複製或符號連結到專案的 public/ 目錄中。
src/: 包含與套件邏輯相關的所有 PHP 類別（例如 Controller/CategoryController.php）。
templates/: 存放依控制器名稱組織的範本（例如 category/show.html.twig）。
tests/: 存放套件的所有測試。
translations/: 存放依網域和語言環境組織的翻譯（例如 AcmeBlogBundle.en.xlf）。

警告

建議的套件結構在 Symfony 5 中已變更，請閱讀Symfony 4.4 套件文件以了解舊結構的相關資訊。

使用新的 AbstractBundle 類別時，套件預設為新的結構。覆寫 Bundle::getPath() 方法以變更為舊結構

        1
2
3
4
5
6
7
        class AcmeBlogBundle extends AbstractBundle
{
    public function getPath(): string
    {
        return __DIR__;
    }
}
    

提示

建議使用 PSR-4 自動載入標準：使用命名空間作為鍵，並使用套件主要類別的位置（相對於 composer.json）作為值。由於主要類別位於套件的 src/ 目錄中

        1
2
3
4
5
6
7
8
9
10
11
12
        {
    "autoload": {
        "psr-4": {
            "Acme\\BlogBundle\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\BlogBundle\\Tests\\": "tests/"
        }
    }
}
    

本作品，包括程式碼範例，皆以創用 CC BY-SA 3.0 授權條款授權。

版本