PHP の Yii フレームワークでの拡張機能のインストールと使用の詳細な説明、yii Framework

详解PHP的Yii框架中扩展的安装与使用，yii框架

扩展是专门设计的在 Yii 应用中随时可拿来使用的，并可重发布的软件包。例如， yiisoft/yii2-debug 扩展在你的应用的每个页面底部添加一个方便用于调试的工具栏，帮助你简单地抓取页面生成的情况。你可以使用扩展来加速你的开发过程。

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

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

修改你的应用的 composer.json 文件，指明你要安装的是哪个扩展（Composer 软件包）。
运行 composer install 来安装指定的扩展。
注意如果你还没有安装 Composer ，你需要先安装。

默认情况，Composer安装的是在 Packagist 中注册的软件包 - 最大的开源 Composer 代码库。你可以在 Packageist 中查找扩展。你也可以创建你自己的代码库然后配置 Composer 来使用它。如果是在开发私有的扩展，并且想只在你的其他工程中共享时，这样做是很有用的。

通过 Composer 安装的扩展会存放在 BasePath/vendor 目录下，这里的 BasePath 指你的应用的 base path。因为 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;

// 生成一个缩略图
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&#63;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 应用程序就能知道安装了哪些扩展 (这些信息可通过 yii\base\Application::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 标准。

你的类的命名空间应以 vendorName\extensionName 起始，其中 extensionName 和项目名相同，除了它没有 yii2- 前缀外。例如，对 yiisoft/yii2-imagine 扩展来说，我们用 yii\imagine 作为它的类的命名空间。

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

类的自举引导

有时候，你可能想让你的扩展在应用的自举过程中执行一些代码。例如，你的扩展可能想响应应用的 beginRequest 事件，做一些环境的设置工作。虽然你可以指导扩展的使用者显式地将你的扩展中的事件句柄附加（绑定）到 beginRequest 事件，但是更好的方法是自动完成。

为实现该目标，你可以创建一个所谓 bootstrapping class （自举类）实现 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 将在每一个请求的自举过程中自动实例化自举类并调用其 yii\base\BootstrapInterface::bootstrap() 方法。

操作数据库

你的扩展可能要存取数据库。不要假设使用你的扩展的应用总是用 Yii::$db 作为数据库连接。你应当在需要访问数据库的类中申明一个 db 属性。这个属性允许你的扩展的用户可定制你的扩展使用哪个 DB 连接。例如，你可以参考 yii\caching\DbCache 类看一下它是如何申明和使用 db 属性的。

如果你的扩展需要创建特定的数据库表，或者修改数据库结构，你应当

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

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

拡張機能ユーザーがこれらのアセットファイルを特定の Web 読み取り可能なフォルダーに手動でコピーできるようにします。アセットバンドルを宣言し、アセット公開メカニズムを利用して、(アセットバンドルにリストされている) ファイルを Web 読み取り可能なフォルダーに自動的にコピーします。
他の人が拡張機能を簡単に使用できるように、2 番目の方法を使用することをお勧めします。

国際化とローカリゼーション

あなたの拡張機能は、さまざまな言語をサポートするアプリで使用される可能性があります。したがって、拡張機能がエンドユーザーにコンテンツを表示する場合は、国際化とローカライゼーション、特に

の実装を試みる必要があります。

拡張機能がエンドユーザー向けの情報を表示する場合、この情報は翻訳できるように Yii::t() でラップする必要があります。開発者の参照のみを目的とした情報 (内部例外情報など) は翻訳する必要はありません。

拡張機能が数値や日付などを表示する場合は、書式設定に yiii18nFormatter の適切な書式設定ルールを使用する必要があります。

テスト

他の人に問題やトラブルを引き起こすことなく、拡張機能が完璧に実行されることは間違いなく必要です。これを実現するには、一般にリリースする前にテストする必要があります。

手動テストだけに頼るのではなく、テストケースを作成して、包括的な範囲で拡張機能をテストすることをお勧めします。新しいバージョンがリリースされる前に、これらのテストを実行して、すべてが正常であることを確認するだけです。 Yii は、単体テスト、受け入れテスト、機能テストを簡単に作成できるようにするテストサポートを提供します。

バージョン管理

各拡張機能にはバージョン番号 (1.0.1 など) を付ける必要があります。バージョン番号に名前を付けるときは、セマンティックバージョン管理を参照して、使用するバージョン番号を決定することをお勧めします。

公開

拡張機能について他の人に知らせるには、拡張機能を公開する必要があります。

拡張機能を初めてリリースする場合は、それを Packagist などの Composer リポジトリに登録する必要があります。その後、バージョン管理リポジトリ (v1.0.1 など) にタグを作成し、Composer コードベースに通知するだけです。他のユーザーは、Composer リポジトリを通じて新しいリリースを見つけ、拡張機能をインストールおよび更新できます。

拡張機能を公開するときは、コードファイルに加えて、他の人が拡張機能を理解して使用できるように、次のコンテンツを含めることも検討する必要があります:

ルートディレクトリにある readme ファイル: 拡張機能の機能と、そのインストール方法と使用方法が説明されています。 Markdown 形式で記述し、ファイル名を readme.md にすることをお勧めします。

ルートディレクトリの変更ログファイル: これには、リリースの各バージョンに対して行われた変更がリストされます。このファイルは Markdown Radical で記述でき、changelog.md という名前が付けられます。
ルートディレクトリのアップグレードファイル: これには、拡張機能を他のバージョンからアップグレードする方法が記載されています。このファイルは Markdown Radical で記述でき、changelog.md という名前が付けられます。
スタートガイド、デモコード、スクリーンショットなど: これらのファイルは、拡張機能が Readme ファイルで完全には説明できない多くの機能を提供する場合に使用されます。
API ドキュメント: 他の人が読みやすく理解できるように、コードを十分に文書化する必要があります。コードを文書化する方法については、オブジェクトクラスファイルを参照してください。
情報: コードのコメントはマークダウン形式で記述できます。 yiisoft/yii2-apidoc 拡張機能は、コードコメントから美しい API ドキュメントを生成する方法を提供します。

情報: 必須ではありませんが、拡張機能が特定のコーディング規約に従うことをお勧めします。コアフレームワークのコードスタイルを参照できます。

コア拡張機能

Yii は、Yii 開発チームによって開発および保守されている次のコア拡張機能を提供します。これらの拡張機能はすべて Packagist に登録されています:

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 のサポートを提供します。基本的なクエリ/検索サポートが含まれており、アクティブレコードモードを実装しているため、アクティブレコードを 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 に基づくテンプレートエンジンを提供します。