0 关注者

扩展

扩展是可再分发的软件包，专门设计用于 Yii 应用程序，并提供现成的功能。例如，yiisoft/yii2-debug 扩展在应用程序每个页面的底部添加了一个方便的调试工具栏，以帮助您更轻松地了解页面的生成方式。您可以使用扩展来加速您的开发过程。您还可以将您的代码打包成扩展，与其他人分享您的优秀作品。

信息：我们使用术语“扩展”来指代 Yii 特定的软件包。对于可以在没有 Yii 的情况下使用的通用软件包，我们将使用术语“包”或“库”来指代它们。

使用扩展

要使用扩展，您需要先安装它。大多数扩展都作为 Composer 包分发，可以通过以下两个简单的步骤安装

  1. 修改应用程序的 composer.json 文件，并指定要安装哪些扩展（Composer 包）。
  2. 运行 composer install 以安装指定的扩展。

请注意，如果您没有安装 Composer，则可能需要安装它。

默认情况下，Composer 安装注册在 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://yiiframework.cn/wiki/",
        "irc": "ircs://irc.libera.chat:6697/yii",
        "source": "https://github.com/yiisoft/yii2"
    },
    "authors": [
        {
            "name": "Antonio Ramirez",
            "email": "[email protected]"
        }
    ],

    // 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 资产插件来启用通过 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 存储库安装或更新扩展。

在扩展的版本中，除了代码文件外，您还应考虑包含以下内容，以帮助其他人了解和使用您的扩展

  • 包根目录中的自述文件：它描述了您的扩展的作用以及如何安装和使用它。我们建议您使用 Markdown 格式编写它，并将文件命名为 readme.md。
  • 包根目录中的更改日志文件：它列出了每个版本中所做的更改。该文件可以使用 Markdown 格式编写，并命名为 changelog.md。
  • 包根目录中的升级文件：它提供了有关如何从扩展的旧版本升级的说明。该文件可以使用 Markdown 格式编写，并命名为 upgrade.md。
  • 教程、演示、屏幕截图等：如果您的扩展提供了许多在自述文件中无法完全涵盖的功能，则需要这些功能。
  • API 文档：您的代码应有良好的文档记录，以便其他人更容易阅读和理解它。您可以参考 BaseObject 类文件 来学习如何记录您的代码。

信息：您的代码注释可以用 Markdown 格式编写。yiisoft/yii2-apidoc 扩展提供了一个工具，您可以根据代码注释生成漂亮的 API 文档。

信息：虽然不是强制要求，但我们建议您的扩展遵守某些编码风格。您可以参考 核心框架代码风格。

核心扩展

Yii 提供以下核心扩展（或 "官方扩展"），这些扩展由 Yii 开发团队开发和维护。它们都已在 Packagist 上注册，并且可以根据 使用扩展 小节中的说明轻松安装。

以下官方扩展适用于 Yii 2.1 及更高版本。您无需为 Yii 2.0 安装它们，因为它们包含在核心框架中。

资产
返回顶部
处理请求：请求处理概述

发现错别字或您认为此页面需要改进？
在 github 上编辑它 !