Yii修行之路 - Extension 扩展

时间 2019-12-07

标签 yii 修行之路 extension 扩展栏目 PHP 繁體版

原文原文链接

简述

扩展是专门设计的在 Yii 应用中随时可拿来使用的，并可重发布的软件包。php

基础

例如， yiisoft/yii2-debug 扩展在你的应用的每一个页面底部添加一个方便用于调试的工具栏，帮助你简单地抓取页面生成的状况。你可使用扩展来加速你的开发过程。node

信息：本文中咱们使用的术语 "扩展" 特指 Yii 软件包。而用术语 "软件包" 和 "库" 指代非 Yii 专用的一般意义上的软件包。

使用扩展要使用扩展，你要先安装它。大多数扩展以 Composer 软件包的形式发布，这样的扩展可采起下述两个步骤来安装：jquery

修改你的应用的 composer.json 文件，指明你要安装的是哪一个扩展（Composer 软件包）。git
运行 composer install 来安装指定的扩展。github

注意若是你尚未安装 Composer ，你须要先安装。web

默认状况，Composer安装的是在 Packagist 中注册的软件包 - 最大的开源 Composer 代码库。你能够在 Packageist 中查找扩展。redis

你也能够建立你本身的代码库而后配置 Composer 来使用它。若是是在开发私有的扩展，而且想只在你的其余工程中共享时，这样作是颇有用的。mongodb

经过 Composer 安装的扩展会存放在 BasePath/vendor 目录下，这里的 BasePath 指你的应用的 base path。由于 Composer 仍是一个依赖管理器，当它安装一个包时，也将安装这个包所依赖的全部软件包。数据库

例如想安装 yiisoft/yii2-imagine 扩展，可按以下示例修改你的 composer.json 文件：npm

{
    // ...
    "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 扩展提供的yiiimagineImage 类：

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。想作到这一点，你应当：

下载扩展压缩文件，解压到 vendor 目录。
若是有，则安装扩展提供的自动加载器。
按指导说明下载和安装全部依赖的扩展。

若是扩展没有提供类的自动加载器，但也遵循了 PSR-4 standard 标准，那么你可使用 Yii 提供的类自动加载器来加载扩展类。你须要作的仅仅是为扩展的根目录声明一个 root alias。

例如，假设在 vendor/mycompany/myext 目录中安装了一个扩展，而且扩展类的命名空间为 myext ，那么你能够在应用配置文件中包含以下代码：

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

建立扩展

在你须要将你的杰做分享给其余人的时候，你可能会考虑建立一个扩展。扩展可包括任何你喜欢的代码，例如助手类、挂件、模块，等等。

建议你按照 Composer package 的条款建立扩展，以便其余人更容易安装和使用。就像上面的讲述的那样。

如下是将扩展建立为一个 Composer 软件包的需遵循的基本步骤。

为你的扩展建一个工程，并将它存放在版本控制代码库中，例如 github.com 。扩展的开发和维护都应该在这个代码库中进行。
在工程的根目录下，建一个 Composer 所需的名为 composer.json 的文件。详情请参考后面的章节。
在一个 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": "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 应用程序就能知道安装了哪些扩展 (这些信息可经过 yiibaseApplication::extensions 访问)。

依赖

你的扩展依赖于 Yii （理所固然）。所以你应当在 composer.json 文件中列出它 (yiisoft/yii2)。

若是你的扩展还依赖其余的扩展或者是第三方库，你也要一并列出来。肯定你也为每个依赖的包列出了适当的版本约束条件 (好比 1.*, @stable) 。当你发布一个稳定版本时，你所依赖的包也应当使用稳定版本。

大多数 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 软件包时，包的内容默认会分别安装到@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 standard 或者 PSR-0 standard 标准。

你的类的命名空间应以 vendorNameextensionName 起始，其中 extensionName 和项目名相同，除了它没有 yii2- 前缀外。例如，对 yiisoft/yii2-imagine 扩展来讲，咱们用 yiiimagine 做为它的类的命名空间。

不要使用 yii、yii2 或者 yiisoft 做为你的 vendor 名。这些名称已由 Yii 内核代码预留使用了。

类的自举引导

有时候，你可能想让你的扩展在应用的自举过程中执行一些代码。

例如，你的扩展可能想响应应用的 beginRequest 事件，作一些环境的设置工做。虽然你能够指导扩展的使用者显式地将你的扩展中的事件句柄附加（绑定）到 beginRequest 事件，可是更好的方法是自动完成。

为实现该目标，你能够建立一个所谓 bootstrapping class （自举类）实现 yiibaseBootstrapInterface 接口。

例如：

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 将在每个请求的自举过程当中自动实例化自举类并调用其 yiibaseBootstrapInterface::bootstrap() 方法。

操做数据库

你的扩展可能要存取数据库。不要假设使用你的扩展的应用老是用 Yii::$db 做为数据库链接。你应当在须要访问数据库的类中申明一个 db 属性。这个属性容许你的扩展的用户可定制你的扩展使用哪一个 DB 链接。例如，你能够参考 yiicachingDbCache 类看一下它是如何申明和使用 db 属性的。

若是你的扩展须要建立特定的数据库表，或者修改数据库结构，你应当

提供数据迁移来操做数据库的结构修改，而不是使用SQL文本文件；
尽可能使迁移文件适用于不一样的 DBMS；
在迁移文件中避免使用 Active Record。

使用 Assets

若是你的扩展是挂件或者模块类型，它有可能须要使用一些 assets 。例如，一个模块可能要显示一些包含图片，JavaScript 和 CSS 的页面。由于扩展的文件都是放在同一个目录之下，安装以后 Web 没法读取，你有两个选择使得这些 asset 文件目录能够经过 Web 读取：

让扩展的用户手动将这些 asset 文件拷贝到特定的 Web 能够读取的文件夹；
申明一个 asset bundle 并依靠 asset 发布机制自动将这些文件（asset bundle 中列出的文件）拷贝到 Web 可读的文件夹。

咱们推荐你使用第二种方法，以便其余人能更容易使用你的扩展。更详细的关于如何处理 assets ，请参照 Assets 章节。

国际化和本地化

你的扩展可能会在支持不一样语言的应用中使用！所以，若是你的扩展要显示内容给终端用户，你应当试着实现国际化和本地化，特别地，

若是扩展为终端用户显示信息，这些信息应该用 Yii::t() 包装起来，以即可以进行翻译。只给开发者参考的信息（如内部异常信息）不须要作翻译。
若是扩展显示数字、日期等，你应该用 yiii18nFormatter 中适当的格式化规则作格式化处理。

测试

你必定想让你的扩展能够无暇地运行而不会给其余人带来问题和麻烦。为达到这个目的，你应当在公开发布前作测试。

推荐你建立测试用例，作全面覆盖的测试你的扩展，而不仅是依赖于手动测试。每次发布新版本前，你只要简单地运行这些测试用例确保一切无缺。 Yii 提供了测试支持，使你更容易写单元测试、验收测试和功能测试。详情请参照 Testing 章节。

版本控制

你应该为每个扩展定一个版本号（如 1.0.1）。咱们推荐你命名版本号时参照 semantic versioning 决定用什么样的版本号。

发布

为使其余人知道你的扩展，你应该公开发布。

若是你首次发布一个扩展，你应该在 Composer 代码库中注册它，例如 Packagist。以后，你所须要作的仅仅是在版本管理库中建立一个 tag （如v1.0.1），而后通知 Composer 代码库。

其余人就能查找到这个新的发布了，并可经过 Composer 代码库安装和更新该扩展。

在发布你的扩展时，除了代码文件，你还应该考虑包含以下内容帮助其余人了解和使用你的扩展：

根目录下的 readme 文件：它描述你的扩展是干什么的以及如何安装和使用。咱们推荐你用 Markdown 的格式来写并将文件命名为readme.md。
根目录下的修改日志文件：它列举每一个版本的发布作了哪些更改。该文件能够用 Markdown 根式编写并命名为 changelog.md。
根目录下的升级文件：它给出如何从其余就版本升级该扩展的指导。该文件能够用 Markdown 根式编写并命名为 changelog.md。
入门指南、演示代码、截屏图示等：若是你的扩展提供了许多功能，在 readme 文件中不能完整描述时，就要用到这些文件。
API 文档：你的代码应当作好文档，让其余人更容易阅读和理解。你能够参照 Object class file 学习如何为你的代码作文档。

信息：你的代码注释能够写成 Markdown 格式。yiisoft/yii2-apidoc 扩展为你提供了一个从你的代码注释生成漂亮的 API 文档。

信息：虽然不作要求，咱们仍是建议你的扩展遵循某个编码规范。你能够参照 core framework code style。

核心扩展

Yii 提供了下列核心扩展，由 Yii 开发团队开发和维护。这些扩展全都在 Packagist 中注册，并像 Using Extensions 章节描述的那样容易安装。

yiisoft/yii2-apidoc: 提供了一个可扩展的、高效的 API 文档生成器。核心框架的 API 文档也是用它生成的。
yiisoft/yii2-authclient: 提供了一套经常使用的认证客户端，例如 Facebook OAuth2 客户端、GitHub OAuth2 客户端。
yiisoft/yii2-bootstrap: 提供了一套挂件，封装了 Bootstrap 的组件和插件。
yiisoft/yii2-codeception: 提供了基于 Codeception 的测试支持。
yiisoft/yii2-debug: 提供了对 Yii 应用的调试支持。当使用该扩展是，在每一个页面的底部将显示一个调试工具条。该扩展还提供了一个独立的页面，以显示更详细的调试信息。
yiisoft/yii2-elasticsearch: 提供对 Elasticsearch 的使用支持。它包含基本的查询/搜索支持，并实现了 Active Record 模式让你能够将活动记录存储在 Elasticsearch 中。
yiisoft/yii2-faker: 提供了使用 Faker 的支持，为你生成模拟数据。
yiisoft/yii2-gii: 提供了一个基于页面的代码生成器，具备高可扩展性，并能用来快速生成模型、表单、模块、CRUD等。
yiisoft/yii2-imagine: 提供了基于 Imagine 的经常使用图像处理功能。
yiisoft/yii2-jui: 提供了一套封装 JQuery UI 的挂件以及它们的交互。
yiisoft/yii2-mongodb: 提供了对 MongoDB 的使用支持。它包含基本的查询、活动记录、数据迁移、缓存、代码生成等特性。
yiisoft/yii2-redis: 提供了对 redis 的使用支持。它包含基本的查询、活动记录、缓存等特性。
yiisoft/yii2-smarty: 提供了一个基于 Smarty 的模板引擎。
yiisoft/yii2-sphinx: 提供了对 Sphinx 的使用支持。它包含基本的查询、活动记录、代码生成等特性。
yiisoft/yii2-swiftmailer: 提供了基于 swiftmailer 的邮件发送功能。
yiisoft/yii2-twig: 提供了一个基于 Twig 的模板引擎。