コンソールアプリケーション

コンソールアプリケーションは、主として、オンラインのウェブアプリケーションが必要とするオフラインの仕事、 例えば、コード生成、検索用インデックスのコンパイル、メール送信等を実行するために使用されます。 Yiiはオブジェクト指向でコンソールアプリケーションを書くためのフレームワークを提供しています。 このフレームワークを使うと、オンラインのウェブアプリケーションが使用するリソース (例えばデータベース接続)にコンソールアプリケーションからアクセスすることが可能になります。

1. 概要 ¶

Yii におけるコンソールのタスクは コマンド(command) という形で提供されます。 すなわち、コンソールのコマンドは CConsoleCommand を継承したクラスとして書かれます。

yiic webapp ツールを使って Yii の初期スケルトンアプリケーションを作成するとき、 protected ディレクトリの下に二つのファイルが有ることに気付くでしょう。

• yiic: これは Linux/Unix で使われる実行スクリプトです
• yiic.bat: これは Windows で使われる実行バッチファイルです

コンソールウィンドウで次のようにコマンドを入力してみましょう。

cd protected
yiic help

上記を実行すると、利用できるコンソールコマンドの一覧が表示されます。 デフォルトでは、利用可能なコマンドには、Yii フレームワークによって提供されるもの (システムコマンドと呼ばれます)と、それぞれのアプリケーションのために ユーザが開発したもの(ユーザコマンドと呼ばれます)が含まれます。

コマンドの使い方を見るためには、以下のように実行します。

yiic help <コマンド名>

そして、コマンドを実行するためには、以下のコマンド書式を使います。

yiic <コマンド名> [引数...]

2. コマンドを作成する ¶

コンソールコマンドは CConsoleApplication::commandPath によって定義される ディレクトリの下にクラスファイルとして保存されます。既定値では、このディレクトリは protected/commands です。

コンソールコマンドのクラスは CConsoleCommand を継承しなければなりません。 また、クラス名は XyzCommand の形式でなければなりません。ここで Xyz は、 コマンド名の最初の文字を大文字にしたものを指します。例えば、sitemap という コマンドは、SitemapCommand というクラス名を使わなければなりません。 コンソールコマンドの名前は大文字と小文字を区別します。

Tip: CConsoleApplication::commandMap を構成すれば、別の命名規約による コマンドクラスを作成したり、別のディレクトリに保存したりすることも出来ます。

新しいコマンドを作成する場合、通常は CConsoleCommand::run() をオーバーライド したり、一つないし複数のコマンドアクションを開発する必要があります。(次のセクションで説明します。)

コンソールコマンドを実行する時は、その CConsoleCommand::run() メソッドが コンソールアプリケーションから呼び出されます。コンソールコマンドのすべての引数も、下記のメソッドシグニチャに従って CConsoleCommand::run() に引き渡されます。

public function run($args) { ... }

ここで $args が、コマンドラインで指定された追加の引数を示しています。

コンソールコマンドの中では、Yii::app() を使ってコンソールアプリケーションの インスタンスにアクセスすることが出来ます。そして、それを通じて、データベース 接続などのリソースにアクセスすることが出来ます(例えば、Yii::app()->db)。 お分かりだと思いますが、Yii::app() の使い方は、ウェブアプリケーションで出来る ことと非常によく似たものです。

情報: バージョン 1.1.1 以降は、同一マシンのすべての Yii アプリケーションによって共有できるグローバルなコマンドを作成することも出来ます。 そうするためには、YII_CONSOLE_COMMANDS という名前の環境変数を定義して、 実際に存在するディレクトリを指し示すようにして下さい。そうすれば、グローバルな コマンドのクラスファイルをこのディレクトリに配置することが出来ます。

3. コンソールコマンドアクション ¶

注意: コンソールコマンドアクションの機能は、バージョン 1.1.5 以降で利用することが出来ます。

コンソールコマンドは、しばしば、異なるコマンドライン引数(必須のものもあれば、 任意のものもある)を取り扱う必要があります。また、異なるサブタスクを扱うために いくつかのサブコマンドを提供しなければならない場合もあります。これらの仕事は、 コンソールコマンドアクションを使って、単純化することが出来ます。

コンソールコマンドアクションはコンソールコマンドクラスのメソッドです。 そのメソッドの名前は、actionXyz の形式でなければなりません。ここで Xyz は 先頭を大文字にしたアクション名を指します。例えば、actionIndex という メソッドは、index という名前のアクションを定義するものです。

特定のアクションを実行するためには、以下のコンソールコマンド書式を使います。

yiic <コマンド名> <アクション名> --option1=value --option2=value2 ...

追加される option-value のペアは、アクションメソッドに名前付きの引数として 渡されます。すなわち、xyz というオプションの値が $xyz という引数として アクションメソッドに引き渡されます。 例として、以下のようなコマンドクラスを定義したとしましょう。

class SitemapCommand extends CConsoleCommand
{
    public function actionIndex($type, $limit=5) { ... }
    public function actionInit() { ... }
}

このとき、次のコンソールコマンドはすべて actionIndex('News', 5) の呼び出しに帰結します。

yiic sitemap index --type=News --limit=5

// $limit はデフォルト値を取る
yiic sitemap index --type=News

// $limit はデフォルト値を取る
// 'index' はデフォルトアクションなので、アクション名を省略することが出来る
yiic sitemap --type=News

// オプションの順序は問題にならない
yiic sitemap index --limit=5 --type=News

オプションが値を指定せずに与えられた場合 (例えば、--type=News のかわりに --type) は、対応するアクションの引数は、boolean で true であると見なされます。

注意: たとえば --type News や -t News のような、別のオプション形式は サポートされていません。

引数は、配列型のヒントをつけて宣言することによって、配列値を取ることが出来ます。

public function actionIndex(array $types) { ... }

配列値を与えるためには、コマンドラインで必要なだけ同じオプションを繰り返します。

yiic sitemap index --types=News --types=Article

上記のコマンドは、最終的に actionIndex(array('News', 'Article')) を呼び出すことになります。

バージョン 1.1.6 以降、Yii は無名のアクション引数とグローバルオプションの使用もサポートするようになりました。 例えば、yiic sitemap index --limit=5 News というコマンドでは、名前付きの引数である limit が 5 という値を取っているのに対して、News という無名の引数が指定されています。

無名の引数を使用するためには、コマンドアクションは $args という名前の引数を宣言しなければなりません。例えば、

public function actionIndex($limit=10, $args=array()) {...}

この $args 配列が全ての無名引数の値を保持します。

グローバルオプションは、コマンドに属する全てのアクションによって共有されるコマンドラインオプションを意味します。 例えば、いくつかのアクションを提供するコマンドにおいて、どのアクションにおいても verbose という名前のオプションを使いたい場合があります。すべてのアクションメソッドで $verbose という引数を宣言することも出来ますが、もっと良い方法は、 それをコマンドクラスの パブリックメンバ変数 として宣言して、verbose をグローバルオプションにすることです。

class SitemapCommand extends CConsoleCommand
{
    public $verbose=false;
    public function actionIndex($type) {...}
}

上記のコードによって、verbose オプションを付けてコマンドを実行することが可能になります。

yiic sitemap index --verbose=1 --type=News

4. コンソールアプリケーションをカスタマイズする ¶

デフォルトでは、アプリケーションが yiic webapp ツールで作成された場合、コンソールアプリケーションの構成ファイルは protected/config/console.php になります。 ウェブアプリケーションの構成ファイルと同じように、このファイルは、コンソールアプリケーションのインスタンスのプロパティ初期値を表す配列を返す PHP スクリプトです。その結果、CConsoleApplication のすべてのパブリックプロパティは、このファイルによって構成することが出来ます。

コンソールコマンドはウェブアプリケーションの必要を満たすために作られることがよくありますので、ウェブアプリケーションによって使用されるリソース(DB 接続など)にアクセスする必要があります。 そうするためには、コンソールアプリケーションの構成ファイルで、以下のように記述します。

return array(
    ......
    'components'=>array(
        'db'=>array(
            ......
        ),
    ),
);

ごらんのように、構成の形式はウェブアプリケーションの構成でする場合と非常によく似たものです。これは、CConsoleApplication と CWebApplication が共通の基本クラスを持っているためです。