yii2/docs/guide-ja/structure-extensions.md

エクステンション

エクステンションは、Yii のアプリケーションで使われることに限定して設計され、そのまますぐに使える機能を提供する 再配布可能なソフトウェアパッケージです。例えば、yiisoft/yii2-debug エクステンションは、 あなたのアプリケーションにおいて、全てのページの末尾に便利なデバッグツールバーを追加して、ページが生成される過程を より容易に把握できるように手助けしてくれます。エクステンションを使うと、あなたの開発プロセスを加速することが出来ます。 また、あなたのコードをエクステンションとしてパッケージ化すると、あなたの優れた仕事を他の人たちと共有することが出来ます。

Info|情報: 「エクステンション」という用語は Yii に限定されたソフトウェアパッケージを指すものとして使用します。 Yii がなくても使用できる汎用のソフトウェアパッケージを指すためには、「パッケージ」または「ライブラリ」という用語を使うことにします。

エクステンションを使う

エクステンションを使うためには、先ずはそれをインストールする必要があります。ほとんどのエクステンションは Composer のパッケージとして配布されていて、次の二つの簡単なステップをふめばインストールすることが出来ます:

1. アプリケーションの composer.json ファイルを修正して、どのエクステンション (Composer パッケージ) をインストールしたいかを指定する。
2. composer install コマンドを走らせて指定したエクステンションをインストールする。

Composer を持っていない場合は、それをインストールする必要があることに注意してください。

既定では、Composer は Packagist に登録されたパッケージをインストールします。Packagist は オープンソース Composer パッケージの最大のレポジトリであり、そこでエクステンションを探すことが出来ます。 また、自分自身のレポジトリを作成 して、それを使うように Composer を構成することも出来ます。これは、あなたがプライベートなエクステンションを開発していて、 それを自分のプロジェクト間でのみ共有したい場合に役に立つ方法です。

Composer によってインストールされるエクステンションは BasePath/vendor ディレクトリに保存されます。ここで BasePath は、アプリケーションの ベースパス を指します。Composer は依存関係を管理するものですから、 パッケージをインストールするときには、それが依存している全てのパッケージをも同時にインストールします。

例えば、yiisoft/yii2-imagine エクステンションをインストールするためには、あなたの composer.json を次のように修正します:

{
    // ...

    "require": {
        // ... 他の依存パッケージ

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

インストール完了後には、BasePath/vendor の下に yiisoft/yii2-imagine ディレクトリが作られている筈です。それと同時に、 imagine/imagine という別のディレクトリも作られて、依存するパッケージがそこにインストールされている筈です。

Info|情報: 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]);

Info|情報: エクステンションのクラスは Yii クラスオートローダ によってオートロードされます。

エクステンションを手作業でインストールする

あまり無いことですが、いくつかまたは全てのエクステンションを Composer に頼らずに手作業でインストールしたい場合があるかもしれません。 そうするためには、次のようにしなければなりません:

1. エクステンションのアーカイブファイルをダウンロードして、vendor ディレクトリに解凍する。
2. もし有れば、エクステンションによって提供されているクラスオートローダをインストールする。
3. 指示に従って、依存するエクステンションを全てダウンロードしインストールする。

エクステンションがクラスオートローダを持っていなくても、PSR-4 標準 に従っている場合は、 Yii によって提供されているクラスオートローダを使ってエクステンションのクラスをオートロードすることが出来ます。必要なことは、 エクステンションのルートディレクトリのための ルートエイリアス を宣言することだけです。 例えば、エクステンションを vendor/mycompany/myext というディレクトリにインストールしたと仮定します。そして、エクステンションの クラスは myext 名前空間の下にあるとします。その場合、アプリケーションのコンフィギュレーションに下記のコードを含めれば良いのです:

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

エクステンションを作成する

あなたの優れたコードを他の人々と共有する必要があると感じたときは、エクステンションを作成することを考慮するのが良いでしょう。 エクステンションは、ヘルパークラス、ウィジェット、モジュールなど、どのようなコードでも含むことが出来ます。

エクステンションは、Composer パッケージ の形式で作成することが推奨されます。そうすれば、 直前の項で説明したように、いっそう容易に他のユーザによってインストールされ、使用されることが出来ます。

以下は、エクステンションを Composer のパッケージとして作成するために踏む基本的なステップです。

1. エクステンションのためのプロジェクトを作成して、github.com などの VCS レポジトリ上でホストする。 エクステンションに関する開発と保守の作業はこのレポジトリ上でなされなければならない。
2. プロジェクトのルートディレクトリに、Composer によって要求される composer.json という名前のファイルを作成する。 更なる詳細については、次の項を参照。
3. エクステンションを Packagist などの Composer レポジトリに登録する。そうすると、他のユーザが エクステンションを見つけて Composer を使ってインストールすることが出来るようになる。

composer.json

全ての Composer パッケージは、ルートディレクトリに composer.json というファイルを持たなければなりません。このファイルは パッケージに関するメタデータを含むものです。このファイルに関する完全な仕様は Composer Manual に記載されています。次の例は、yiisoft/yii2-imagine エクステンションのための composer.json ファイルを示すものです:

{
    // パッケージ名
    "name": "yiisoft/yii2-imagine",

    // パッケージタイプ
    "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"
        }
    ],

    // 依存パッケージ
    "require": {
        "yiisoft/yii2": "*",
        "imagine/imagine": "v0.5.0"
    },

    // クラスのオートロードの仕様
    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}

パッケージ名

全ての Composer パッケージは、他の全てパッケージに対して唯一のものとして特定できるような名前を持たなければなりません。 パッケージ名の形式は vendorName/projectName です。例えば、yiisoft/yii2-imagine というパッケージ名の中では、 ベンダー名とプロジェクト名は、それぞれ、yiisoft と yii2-imagine です。

ベンダー名として yiisoft を使ってはいけません。これは Yii のコアコードに使うために予約されています。

プロジェクト名には、Yii 2 エクステンションを表す yii2- を前置することを推奨します。例えば、myname/yii2-mywidget です。 このようにすると、ユーザはパッケージが Yii 2 エクステンションであることをより容易に知ることが出来ます。

パッケージタイプ

パッケージがインストールされたときに Yii のエクステンションとして認識されるように、エクステンションのパッケージタイプを yii2-extension と指定することは重要なことです。

ユーザが composer install を走らせてエクステンションをインストールすると、vendor/yiisoft/extensions.php というファイルが 自動的に更新されて、新しいエクステンションに関する情報を含むようになります。このファイルから、Yii のアプリケーションは どんなエクステンションがインストールされているかを知ることが出来ます (その情報には、yii\base\Application::extensions を通じてアクセス出来ます)。

依存パッケージ

あなたのエクステンションは Yii に依存します (当然ですね)。ですから、composer.json の require エントリのリストに それ (yiisoft/yii2) を挙げなければなりません。あなたのエクステンションがその他のエクステンションやサードパーティの ライブラリに依存する場合は、それらもリストに挙げなければなりません。それぞれの依存パッケージについて、適切なバージョン制約 (例えば 1.* や @stable) を指定することも忘れてはなりません。あなたのエクステンションを安定バージョンとしてリリースする場合は 安定した依存パッケージを使ってください。

たいていの JavaScript/CSS パッケージは、Composer ではなく、Bower および/または NPM を使って管理されています。Yii は Composer アセットプラグイン を使って、この種のパッケージを Composer によって管理することを可能にしています。あなたのエクステンションが Bower パッケージに 依存している場合でも、次のように、composer.json に依存パッケージをリストアップすることが簡単に出来ます:

{
    // 依存パッケージ
    "require": {
        "bower-asset/jquery": ">=1.11.*"
    }
}

上記のコードは、エクステンションが jquery Bower パッケージに依存することを述べています。一般に、composer.json の中で Bower パッケージを指すためには bower-asset/PackageName を使うことが出来ます。そして、NPM パッケージを指すためには npm-asset/PackageName を使うことが出来ます。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 () {
             // ここで何かをする
        });
    }
}

そして、次のように、このクラスを composer.json ファイルのリストに挙げます。

{
    // ...

    "extra": {
        "bootstrap": "myname\\mywidget\\MyBootstrapClass"
    }
}

このエクステンションがアプリケーションにインストールされると、すべてのリクエストのブートストラップの過程において、毎回、 Yii が自動的にブートストラップクラスのインスタンスを作成し、その yii\base\BootstrapInterface::bootstrap() メソッドを呼びます。

データベースを扱う

あなたのエクステンションはデータベースにアクセスする必要があるかも知れません。エクステンションを使うアプリケーションが 常に Yii::$db を DB 接続として使用すると仮定してはいけません。その代りに、DB アクセスを必要とするクラスのために db プロパティを宣言すべきです。このプロパティによって、エクステンションのユーザは、エクステンションにどの DB 接続を使わせるかを カスタマイズすることが出来るようになります。その一例として、yii\caching\DbCache クラスを参照して、それがどのように db プロパティを宣言して使っているかを見ることが出来ます。

あなたのエクステンションが特定の DB テーブルを作成したり、DB スキーマを変更したりする必要がある場合は、次のようにするべきです。

• DB スキーマを操作するために、平文の SQL ファイルを使うのではなく、マイグレーション を提供する。
• マイグレーションをさまざまな DBMS に適用可能なものするように努める。
• マイグレーションの中では アクティブレコード の使用を避ける。

アセットを使う

あなたのエクステンションがウィジェットかモジュールである場合は、動作するために何らかの assets が必要である可能性が高いでしょう。例えば、モジュールは、画像、JavaScript、そして CSS を含むページをいくつか表示するでしょう。 エクステンションのファイルは、全て、アプリケーションにインストールされるときに、ウェブからアクセス出来ない同じディレクトリ の下に配置されます。そのため、次のどちらかの方法を使って、アセットファイルをウェブから直接アクセス出来るようにしなければなりません。

• アセットファイルをウェブからアクセス出来る特定のフォルダに手作業でコピーするように、エクステンションのユーザにお願いする。
• アセットバンドル を宣言し、アセット発行メカニズムに頼って、アセットバンドルにリスとされているファイルを ウェブからアクセス出来るフォルダに自動的にコピーする。

あなたのエクステンションが他の人々にとってより一層使いやすいものになるように、第二の方法をとることを推奨します。 アセットの取り扱い一般に関する更なる詳細は アセット の節を参照してください。

国際化と地域化

あなたのエクステンションは、さまざまな言語をサポートするアプリケーションによって使われるかもしれません。従って、 あなたのエクステンションがエンドユーザにコンテンツを表示するものである場合は、それを 国際化 するように努めるべきです。具体的には、

• エクステンションがエンドユーザに向けたメッセージを表示する場合は、翻訳することが出来るようにメッセージを Yii::t() で包むべきです。開発者に向けられたメッセージ (内部的な例外のメッセージなど) は翻訳される必要はありません。
• エクステンションが数値や日付などを表示する場合は、yii\i18n\Formatter を適切な書式化の規則とともに使って書式設定すべきです。

更なる詳細については、国際化 の節を参照してください。

テスト

あなたは、あなたのエクステンションが他の人々に問題をもたらすことなく完璧に動作することを望むでしょう。この目的を達するためには、 あなたのエクステンションを公開する前にテストすべきです。

手作業のテストに頼るのではなく、あなたのエクステンションのコードをカバーするさまざまなテストケースを作成することが推奨されます。 あなたのエクステンションの新しいバージョンを公開する前には、毎回、単にそれらのテストケースを走らせれば、全てが良い状態にあることを 確認することが出来ます。Yii はテストのサポートを提供しており、それよって、ユニットテスト、機能テスト、承認テストを書くことが 一層簡単に出来るようになっています。更なる詳細については、テスト の節を参照してください。

バージョン管理

エクステンションのリリースごとにバージョン番号 (例えば 1.0.1) を付けるべきです。 どのようなバージョン番号を付けるべきかを決定するときは、セマンティックバージョニング の慣行に従うことを推奨します。

リリース(公開)

他の人々にあなたのエクステンションを知ってもらうためには、それをリリース(公開)する必要があります。

エクステンションをリリースするのが初めての場合は、Packagist などの Composer レポジトリに エクステンションを登録するべきです。その後は、あなたがしなければならない仕事は、エクステンションの VCS レポジトリでリリースタグ (例えば v1.0.1) を作成して Composer レポジトリに新しいリリースについて通知するだけのことになります。そして、 人々が新しいリリースを見出すことが出来るようになり、Composer レポジトリを通じてエクステンションをインストールしたり アップデートしたりするようになります。

エクステンションのリリースには、人々があなたのエクステンションについて知ったり、エクステンションを使ったりするのを助けるために、 コードファイル以外に下記のものを含めることを考慮すべきです。

• パッケージのルートディレクトリに readme ファイル: あなたのエクステンションが何をするものか、そして、 どのようにインストールして使うものかを説明するものです。Markdown 形式で書いて、readme.md という名前にすることを推奨します。
• パッケージのルートディレクトリに changelog ファイル: それぞれのリリースで何が変ったかを一覧表示するものです。 このファイルは Markdown 形式で書いて changelog.md と名付けることが出来ます。
• パッケージのルートディレクトリに upgrade ファイル: エクステンションの古いリリースからのアップグレード方法について説明するものです。 このファイルは Markdown 形式で書いて upgrade.md と名付けることが出来ます。
• チュートリアル、デモ、スクリーンショットなど: あなたのエクステンションが readme ファイルでは十分にカバーできないほど 多くの機能を提供するものである場合は、これらが必要になります。
• API ドキュメント: あなたのコードは、他の人々が読んで理解することがより一層容易に出来るように、十分な解説を含むべきです。 Object のクラスファイル を参照すると、 コードに解説を加える方法を学ぶことが出来ます。

Info|情報: コードのコメントを Markdown 形式で書くことが出来ます。yiisoft/yii2-apidoc エクステンションは、 コードのコメントに基づいて綺麗な API ドキュメントを生成するツールを提供しています。

Info|情報: これは要求ではありませんが、あなたのエクステンションも一定のコーディングスタイルを守るのが良いと思います。 コアフレームワークコードスタイル を参照してください。

コアエクステンション

Yii は下記のコアエクステンションを提供しています。これらは Yii 開発チームによって開発され保守されているものです。 全て Packagist に登録され、エクステンションを使う の項で説明したように、 簡単にインストールすることが出来ます。

• yiisoft/yii2-apidoc: 拡張可能で高性能な API ドキュメント生成機能を提供します。コアフレームワークの API ドキュメントを生成するためにも使われています。
• yiisoft/yii2-authclient: Facebook OAuth2 クライアント、GitHub OAuth2 クライアントなど、よく使われる一連の auth クライアントを提供します。
• 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 に基づいたテンプレートエンジンを提供します。