シェルとタスクとコンソール¶

CakePHP のコンソール¶

このセクションでは、コマンドラインにおける CakePHP をご紹介します。 もし過去に cron ジョブやコマンドライン・スクリプトから自分の CakePHP の MVC クラスにアクセスできたら便利なのにと思ったことがあれば、 このセクションがその道しるべとなるでしょう。

PHP ではファイルシステムやアプリケーションをより柔軟に使えるように、 これらへのインターフェースを備えた CLI クライアント機能を提供しています。 CakePHP コンソールでは、シェルスクリプト作成のためのフレームワークを提供 しています。コンソールではディスパッチタイプのセットアップを使って シェルやタスクをロードし、それらへパラメータを渡します。

詳細に入る前に、CakePHP コンソールがちゃんと動くことを確認しておきましょう。 まずはシステムのシェルを起動する必要があります。このセクションで示している 例は bash のものですが、CakePHP コンソールは Windows 互換でもあります。それでは bash からコンソールプログラムを動かしてみましょう。これの例ではユーザがすでに bash プロンプトにログインしており、CakePHP アプリケーションのルートにいること を想定しています。

CakePHP アプリケーションの中には Console というディレクトリがあり、 この中にアプリケーションのためのすべてのシェルやタスクを格納します。 またここには以下の実行ファイルがあります。

$ cd /path/to/cakephp/app
$ ./Console/cake

システムのパスの中にコアとなる cake 実行ファイル（を含むディレクトリ）を 追加するのもよいでしょう。これでどこにいても cake コマンドが使えるように なり、新しいプロジェクトを生成する際にも便利です。 cake をシステム全体 で使えるようにするやり方は システムパスに cake を追加 にあります。

引数なしでコンソールを起動すると、以下のメッセージが表示されます （訳注：便宜上、一部和訳しています）:

Welcome to CakePHP v2.0.0 Console
---------------------------------------------------------------
App : app
Path: /path/to/cakephp/app/
---------------------------------------------------------------
現在のパス:

 -app: app
 -working: /path/to/cakephp/app
 -root: /path/to/cakephp/
 -core: /path/to/cakephp/core

パスの変更:

作業パスは自分のアプリケーションパスと同じである必要があります。
パスを変更するには '-app' を使います。
例: -app cakephpへの相対パス または -app /cakephpへの絶対パス

利用できるシェル:

 acl [CORE]                              i18n [CORE]
 api [CORE]                              import [app]
 bake [CORE]                             schema [CORE]
 command_list [CORE]                     testsuite [CORE]
 console [CORE]                          upgrade [CORE]

コマンドを実行するには 'cake シェル名 [引数]' にようにタイプします。
'cake シェル名 help' で特定のコマンドに対するヘルプが表示されます。

先頭部分にはパスに関連する情報が表示されます。これはファイルシステム上の 異なる場所からコンソールを動かしている場合に便利です。

CakePHP コンソールを自分のシステムパスに追加しているユーザが多ければ、cake コンソールには簡単にアクセスできます。表示されているのは working, root, app, core のパスで、それぞれコンソールの場所が変更されていてもその位置を 確認できます。作業したい app フォルダを変更するには単にそこへのパスをcake コマンドに知らせてやるだけです。次に app フォルダの設定例を示しますが、その際 コンソールのフォルダをあなたの PATH に追加してあるとものとみなしています。

$ cake -app /path/to/cakephp/app

指定するパスは、現在の作業ディレクトリへの相対パスでも絶対パスでも構いません。

シェルの作成¶

早速コンソールで動くシェルを作ってみましょう。この例ではシンプルな hello world シェルを作ります。お使いのアプリケーションの Console/Command ディレクトリで HelloShell.php を作ってください。その中に以下のコードを書きます。

class HelloShell extends AppShell {
    public function main() {
        $this->out('Hello world.');
    }
}

シェルクラスの慣習として、クラス名はファイル名に Shell サフィックス（接尾辞）を 付けたものとします。このシェルの中に main() メソッドを作成します。シェルが 追加コマンド（引数）なしで起動された場合、このメソッドが呼ばれます。この後、 多少コマンドを追加していきますが、現時点では単にシェルを起動してみましょう。 自分のアプリケーションディレクトリ (app) で、以下を実行します。

Console/cake hello

以下の出力が行われます。

Welcome to CakePHP v2.0.0 Console
---------------------------------------------------------------
App : app
Path: /Users/markstory/Sites/cake_dev/app/
---------------------------------------------------------------
Hello world.

すでに述べたように、シェルの main() メソッドはシェルに他のコマンドや引数が 与えられない場合、常に呼ばれる特別なメソッドです。HelloShell は AppShell を 拡張していますね。 AppController と同様に、AppShell はあなたの共通関数や ロジックのすべてを含む基本的なクラスを提供します。AppShell は app/Console/Command/AppShell.php を作ることにより定義されます。もしこれが 存在しない場合、CakePHP はビルトインされたものを使います。main メソッドの使い方が ある程度わかったら、次は以下のように別のコマンドを追加してみましょう。

class HelloShell extends AppShell {
    public function main() {
        $this->out('Hello world.');
    }

    public function hey_there() {
        $this->out('Hey there ' . $this->args[0]);
    }
}

このファイルを作って Console/cake hello hey_there あなたの名前 を実行 すると、ご自分の名前が表示されるはずです。public メソッドのうち頭に _ が 付かないものは、コマンドラインから呼び出せます。 直前の例の hey_there メソッドの中では $this->args を使っています。 これはコマンドに対して与えられた（指定順序が意味を持つ）引数が、与えられた 順に配列として保持されています。シェルアプリケーションではスイッチや オプションを使うこともでき、これらは $this->params もしくは param() メソッド経由で参照可能ですが、ここではプロパティ名を示すに留めます。

main() メソッドを使っている場合、位置引数は参照できません。これは 第一引数として指定された引数またはオプションが、コマンド名と解釈される からです。引数やオプションを使いたい場合は、 main ではない 何か他のメソッド名を使う必要があります。

class UserShell extends AppShell {
    public $uses = array('User');

    public function show() {
        $user = $this->User->findByUsername($this->args[0]);
        $this->out(print_r($user, true));
    }
}

シェルのタスク¶

より高度なコンソールアプリケーションを開発する場合には、 多くのシェル間で共有される再利用可能なクラスとして機能を構成したいでしょう。 タスクによりコマンドをクラスに展開できます。たとえば bake は、 そのほとんどがタスクにより作られています。 $tasks プロパティを使ってシェルのタスクを定義できます。

class UserShell extends AppShell {
    public $tasks = array('Template');
}

プラグインからタスクを使うには、標準の プラグイン記法 を使用します。 タスクは Console/Command/Task/ に、クラスにちなんで名付けられたファイルに 格納されます。たとえば新たに 'FileGenerator' タスクを作成したい場合は Console/Command/Task/FileGeneratorTask.php を作成することになります。

各タスクは、少なくとも execute() メソッドを実装する必要があります。タスクが 呼び出された時、ShellDispatcher はこのメソッドを呼び出します。タスククラスは 次のようになります。

class FileGeneratorTask extends Shell {
    public $uses = array('User');
    public function execute() {

    }
}

シェルはプロパティとしてもタスクにアクセスできますので、 コンポーネント と同様に再利用可能な部品としてタスクを利用できます。

// Console/Command/SeaShell.php に作成
class SeaShell extends AppShell {
    public $tasks = array('Sound'); // Console/Command/Task/SoundTask.php に作成
    public function main() {
        $this->Sound->execute();
    }
}

また、コマンドラインからタスクに直接アクセスすることができます。

$ cake sea sound

$Project = $this->Tasks->load('Project');

$ProgressBar = $this->Tasks->load('ProgressBar.ProgressBar');

シェルから他のシェルを呼び出し¶

シェルからは、もはや $this->Dispatch を通した ShellDispatcher への直接の アクセスができません。あるシェルから他のシェルを呼び出したいケースは多々 あると思います。他のシェルを呼び出すには Shell::dispatchShell() を使います。 サブシェル側では引数を受け取るための argv が使えます。引数やオプションは 可変引数もしくは文字列として指定できます。

// 文字列で渡す
$this->dispatchShell('schema create Blog --plugin Blog');

// 配列で渡す
$this->dispatchShell('schema', 'create', 'Blog', '--plugin', 'Blog');

上記は、プラグインのシェルの中からプラグイン用のスキーマを作るために schema シェルを 呼んでいます。

コンソール出力のレベル¶

シェルでは往々にして異なったレベルの冗長出力が必要になります。cron ジョブ として動いている場合はほとんどの出力は不要です。また、シェルが出力する メッセージを見たくないというケースもあるでしょう。このような場合、出力を 適切に制御するための出力レベルが使えます。シェルの利用者は、シェルを 呼び出す際に正しいフラグをセットすることで、自分が見たい詳細レベルの設定 ができます。 Shell::out() ではデフォルトで３種類の出力を サポートしています。

• QUIET - 必須のメッセージであり、静かな（必要最小限の）出力モードでも表示される。

• NORMAL - 通常利用におけるデフォルトのレベル。

• VERBOSE - 毎日利用には冗長すぎるメッセージを表示。ただデバッグ時には有用。

以下のように出力を指定できます。

// すべてのレベルで表示されます。
$this->out('Quiet message', 1, Shell::QUIET);

// QUIET 出力時には表示されません。
$this->out('normal message', 1, Shell::NORMAL);
$this->out('loud message', 1, Shell::VERBOSE);

// VERBOSE 出力時のみ表示されます。
$this->out('extra message', 1, Shell::VERBOSE);

シェルの実行時に --quiet や --verbose を使うことで出力を制御できます。 これらのオプションはデフォルトで組み込まれていて、いつでも CakePHP シェル内部の 出力レベルを制御できるように考慮されています。

出力のスタイル¶

ちょうど HTML のようなタグを埋め込むことで、出力のスタイルを変更することが できます。ConsoleOutput はこれらのタグを正しい ansi コードシーケンスに変換 したり、ansi コードをサポートしないコンソールではタグを除去します。 スタイルはいくつかビルトインされたものがありますが、自分で作成することも 可能です。ビルトインされたものは以下の通りです。

• error エラーメッセージ。赤いアンダーライン。

• warning 警告メッセージ。黄色いテキスト。

• info 情報メッセージ。水色のテキスト。

• comment 追加情報。青色のテキスト

• question 質問事項。シェルが自動的に追加する。

$this->stdout->styles() を使ってさらに多くのスタイルを追加できます。 新しいスタイルを追加するには以下のようにします。

$this->stdout->styles('flashy', array('text' => 'magenta', 'blink' => true));

これで <flashy> というタグが有効になり、ansi カラーが有効な端末であれば、 $this->out('<flashy>うわ！</flashy> 何か変になった'); の場合の表示は 色がマゼンタでブリンクになります。スタイルを定義する際は text と background 属性として以下の色が指定できます:

• black

• red

• green

• yellow

• blue

• magenta

• cyan

• white

さらに以下のオプションをブール型のスイッチとして指定できます。 値が真の場合に有効になります。

• bold

• underline

• blink

• reverse

スタイルを追加すると ConsoleOutput のすべてのインスタンスでも有効になります。 なので stdout と stderr 両方のオブジェクトでこれらを再定義する必要はありません。

$this->stdout->outputAs(ConsoleOutput::RAW);

オプションの設定とヘルプの生成¶

class ConsoleOptionParser¶

CakePHP におけるオプションのパースは、コマンドラインのそれに比べて少しずつ 変わってきています。2.0 では親しみやすいコマンドラインオプションや引数パーサ の提供を ConsoleOptionParser が助けてくれます。

OptionParsers は同時に２つのことを実現します。１つ目は、基本的なバリデー ションと独自のコードにより、オプションと引数を定義することです。２つ目は、 きれいにフォーマットされたヘルプファイルを生成するためのドキュメントの 提供です。

コンソールのフレームワークは $this->getOptionParser() を呼び出すことにより あなたのシェルのオプションパーサを取得します。このメソッドをオーバーライド することで、オプションパーサがあなたのシェルの期待する入力にマッチするように なります。さらにサブコマンドオプションパーサを設定すると、サブコマンドと タスクについて異なったオプションパーサを定義できます。ConsoleOptionParser は柔軟なインターフェースを実装しており、また複数のオプション／引数を一度に 簡単に設定できるようなメソッドを備えています。

public function getOptionParser() {
    $parser = parent::getOptionParser();
    // パーサの設定
    return $parser;
}

public function getOptionParser() {
    $parser = parent::getOptionParser();
    $parser->addArgument('type', array(
        'help' => 'フルパスもしくはクラスの型のいずれか。'
    ))->addArgument('className', array(
        'help' => 'CakePHP コアのクラス名（Component, HtmlHelper 等)。'
    ))->addOption('method', array(
        'short' => 'm',
        'help' => __('The specific method you want help on.')
    ))->description(__('Lookup doc block comments for classes in CakePHP.'));
    return $parser;
}

// 一度に複数行を設定
$parser->description(array('１行目', '２行目'));

// 現在の値を取得する
$parser->description();

// 一度に複数行を設定
$parser->epilog(array('１行目', '２行目'));

// 現在の値を取得する
$parser->epilog();

$parser->addArgument('model', array('help' => 'bake するモデル'));

$parser->addArguments(array(
    'node', array('help' => '生成するノード', 'required' => true),
    'parent' => array('help' => '親ノード', 'required' => true)
));

$parser->addArgument('type', array(
    'help' => 'これとやり取りするノードの型',
    'required' => true,
    'choices' => array('aro', 'aco')
));

$parser->addOption('connection', array(
    'short' => 'c'
    'help' => 'connection',
    'default' => 'default'
));

$parser->addOption('no-commit', array('boolean' => true));

$parser->addOptions(array(
    'node' => array('short' => 'n', 'help' => '生成するノード'),
    'parent' => array('short' => 'p', 'help' => '親ノード')
));

$parser->addOption('accept', array(
    'help' => 'What version to accept.',
    'choices' => array('working', 'theirs', 'mine')
));

$parser->addOption('verbose', array(
    'help' => '冗長出力を有効にする.',
    'boolean' => true
));

if ($this->params['verbose']) {
    // 何かします
}

// 2.7 なら
if ($this->param('verbose')) {
    // 何かします
}

$parser->addSubcommand('model', array(
    'help' => 'Bake a model',
    'parser' => $this->Model->getOptionParser()
));

$parser->addSubcommand('check', array(
    'help' => __('Check the permissions between an ACO and ARO.'),
    'parser' => array(
        'description' => array(
            __("Use this command to grant ACL permissions. Once executed, the ARO "),
            __("specified (and its children, if any) will have ALLOW access to the"),
            __("specified ACO action (and the ACO's children, if any).")
        ),
        'arguments' => array(
            'aro' => array('help' => __('ARO to check.'), 'required' => true),
            'aco' => array('help' => __('ACO to check.'), 'required' => true),
            'action' => array('help' => __('Action to check'))
        )
    )
));

public function getOptionParser() {
    return ConsoleOptionParser::buildFromArray(array(
        'description' => array(
            __("Use this command to grant ACL permissions. Once executed, the "),
            __("ARO specified (and its children, if any) will have ALLOW access "),
            __("to the specified ACO action (and the ACO's children, if any).")
        ),
        'arguments' => array(
            'aro' => array('help' => __('ARO to check.'), 'required' => true),
            'aco' => array('help' => __('ACO to check.'), 'required' => true),
            'action' => array('help' => __('Action to check'))
        )
    ));
}

cake bake --help
cake bake -h

cake bake model --help
cake bake model -h

cake bake --help xml
cake bake -h xml

<?xml version="1.0"?>
<shell>
    <command>bake fixture</command>
    <description>Generate fixtures for use with the test suite. You can use
        `bake fixture all` to bake all fixtures.</description>
    <epilog>
        Omitting all arguments and options will enter into an interactive
        mode.
    </epilog>
    <subcommands/>
    <options>
        <option name="--help" short="-h" boolean="1">
            <default/>
            <choices/>
        </option>
        <option name="--verbose" short="-v" boolean="1">
            <default/>
            <choices/>
        </option>
        <option name="--quiet" short="-q" boolean="1">
            <default/>
            <choices/>
        </option>
        <option name="--count" short="-n" boolean="">
            <default>10</default>
            <choices/>
        </option>
        <option name="--connection" short="-c" boolean="">
            <default>default</default>
            <choices/>
        </option>
        <option name="--plugin" short="-p" boolean="">
            <default/>
            <choices/>
        </option>
        <option name="--records" short="-r" boolean="1">
            <default/>
            <choices/>
        </option>
    </options>
    <arguments>
        <argument name="name" help="Name of the fixture to bake.
            Can use Plugin.name to bake plugin fixtures." required="">
            <choices/>
        </argument>
    </arguments>
</shell>

シェル／CLI におけるルーティング¶

コマンドライン・インターフェース (CLI)、特にあなたのシェルやタスクでは、 env('HTTP_HOST') やその他のウェブブラウザ固有の変数がセットされていません。

Router::url() を使ってレポートを作成したり電子メールを送ったりする場合、 それらにはデフォルトホスト http://localhost/ が構成に含まれており、 そのため結果として無効な URL となってしまいます。こういったケースでは、 ドメインを手作業で設定する必要があります。これを、たとえばブート ストラップまたは config で、コンフィグ値 App.fullBaseUrl を使って 設定できます。

電子メールを送る場合は、CakeEmail クラスでメールを送る際のホストを指定する 必要があります。

$Email = new CakeEmail();
$Email->domain('www.example.org');

これにより生成されるメッセージ ID は有効で、また送信元ドメイン名にも合致 したものになります。

シェル API¶

class AppShell¶

AppShell はあなたのすべてのシェルの基底クラスとして使えます。これは Shell を継承し、また Console/Command/AppShell.php として置かれている必要があります。

class Shell($stdout = null, $stderr = null, $stdin = null)¶

Shell はすべてのシェルの基底クラスであり、ユーザの入力と対話するための 多くの関数を提供し、また生成されたエラーをテキストとして出力します。

property Shell::$tasks¶

このシェル／タスクでロードしたいタスクの配列。

property Shell::$uses¶

このシェル／タスクでロードしたいモデルの配列。

Shell::clear()¶

出力バッファの中身をクリアします。

Shell::param($name)¶

オプション・パラメータの値を取得します。パラメータが存在しない場合は、 null を返します。

バージョン 2.7 で追加.

Shell::createFile($path, $contents)¶

パラメータ:

• $path (string) -- 生成したいファイルへの絶対パス。

• $contents (string) -- ファイルに出力したいコンテンツ。

与えられたパスでファイルを生成します。ファイルが存在する場合、対話的 シェルであれば警告が発せられ、上書きするかどうか聞かれます。シェルの interactive プロパティが false の場合、質問は行われず、単にファイルは上書きされます。

Shell::dispatchShell()¶

コマンドから別のシェルに制御を移します。 Controller::requestAction() と似ていますが、他のシェルから シェルを起動することを目的としています。

参照 シェルから他のシェルを呼び出し.

Shell::err($message = null, $newlines = 1)¶

パラメータ:

• $message (string) -- 表示するメッセージ。

• $newlines (integer) -- メッセージの後の改行する数。

stderr へ出力するメソッドです。 Shell::out() のように動作します。

Shell::error($title, $message = null)¶

パラメータ:

• $title (string) -- エラーのタイトル

• $message (string) -- オプションのエラーメッセージ

整形されたエラーメッセージを表示し、ステータスコード 1 でアプリケーションを終了します。

Shell::getOptionParser()¶

シェルのサブ・パーサーと共に ConsoleOptionParser オブジェクトを返します。

Shell::hasMethod($name)¶

シェルに与えられた名前を持つ呼び出し可能なメソッドがあるかどうかを調べます。

Shell::hasTask($task)¶

シェルに与えられた名前を持つタスクがあるかどうかを調べます。

Shell::hr($newlines = 0, $width = 63)¶

パラメータ:

• $newlines (int) -- 線を引く前に置くべき改行の数。

• $width (int) -- 線の長さ。

いくつかの改行の後に水平線を引きます。

Shell::in($prompt, $options = null, $default = null)¶

パラメータ:

• $prompt (string) -- 利用者に表示するプロンプト。

• $options (array) -- 入力の選択肢。利用者がこの中から選ぶ。無効なオプションを選んだ場合、 再度の入力が求められる。

• $default (string) -- もしあれば、これをデフォルトのオプションとする。

このメソッドはユーザとの対話を助ける、対話的なシェルを作成します。 プロンプトに対するユーザの入力値を返し、またユーザに有効な選択肢を提示します。

$selection = $this->in('Red or Green?', array('R', 'G'), 'R');

入力値のバリデーションでは、大文字小文字は区別されません。

Shell::initialize()¶

シェルを初期化し、サブクラスのコンストラクタとして動作します。 またシェルの実行に先立って、タスクの設定を行います。

Shell::loadTasks()¶

Shell::$tasks で public として定義されているタスクをロードします。

Shell::nl($multiplier = 1)¶

パラメータ:

• $multiplier (int) -- 改行動作を繰り返す回数

指定数の改行を出力します。

Shell::out($message = null, $newlines = 1, $level = Shell::NORMAL)¶

パラメータ:

• $message (string) -- 表示するメッセージ。

• $newlines (integer) -- メッセージの後に出力する改行の数。

• $level (integer) -- このメッセージを表示するべき コンソール出力のレベル の最大値。

ユーザへの出力を生成するためのもっとも普通のやり方です。 レベルを指定することで、シェルの出力の度合いを制限できます。 out() ではカラー出力タグも出力できますので、お使いのシステムが サポートしていれば色付きの出力が行えます。テキストのカラーリング のためにいくつか組み込みのスタイルを持っており、また自分でスタイルを 定義することもできます。

• error エラーメッセージ。

• warning 警告メッセージ。

• info 情報メッセージ。

• comment 追加メッセージ。

• question マゼンタのテキスト。ユーザへのプロンプトに使われます。

スタイルタグでメッセージを書式化することにより、スタイルを適用した出力が行えます。

$this->out('<warning>これはファイルシステムからデータを消去します.</warning>');

*nix システムのデフォルトでは、ConsoleOutput オブジェクトのデフォルトは カラー出力です。Windows システムでは、 ANSICON 環境変数が存在しない 限りはプレインテキスト出力がデフォルトです。

Shell::overwrite($message = null, $newlines = 1, $size = null)¶

パラメータ:

• $message (string) -- 表示するメッセージ

• $newlines (integer) -- メッセージの後に出力する改行の数

• $size (integer) -- 上書きするバイト数

プログレスバーの生成や大量の行出力を避けるのに便利なメソッドです。

注意: 改行コードを含む文字列は上書きできません。

バージョン 2.6 で追加.

Shell::runCommand($command, $argv)¶

指定された引数によりシェルを実行します。

タスクへの呼び出しを代行し、クラス内部のメソッドを解決します。 コマンドは以下の順序で検索されます。

• シェル上のメソッド

• タスク名とのマッチング

• main() メソッド

シェルが main() メソッドを実装していれば、メソッドの呼び出しに失敗した ものはすべて、argv に元々のメソッド名を入れた形で main() に送られます。

Shell::shortPath($file)¶

ファイルの絶対パスを読みやすくします。

Shell::startup()¶

シェルを起動してウェルカムメッセージを表示します。コマンドや main の実行に 先立ってチェックや設定を可能とします。

ウェルカム情報を出力したくない場合は、このメソッドをオーバーライドします。 そうしない場合、そこまでのコマンドの流れを変更します。

Shell::wrapText($text, $options = array())¶

テキストブロックを折り返します。幅とインデント文字列を設定できます。

パラメータ:

• $text (string) -- 整形するテキスト

• $options (array) --

• width 折り返し幅。デフォルトは 72。

• wordWrap 単語の区切り（スペース）のみで折り返します。デフォルトは true。

• indent 指定された文字列でインデントします。デフォルトは null。

その他のトピック¶