PHP をコマンドラインから使用する

4.3 以降で PHP は Command Line Interface を意味する CLI という名前の新しい SAPI 型 (Server Application Programming Interface)をサポートします。 名前から分かるように、この SAPI 型は、 PHP によるシェル(またはデスクトップ)アプリケーションの開発を 主な対象としています。 CLI SAPI と他の SAPI の間には、 いくつかの違いがあります。本章では、これらについて詳細を説明します。 CLI と CGI はその振る舞いの多くが 共通であるにもかかわらず、違う SAPI であることに留意してください。

CLI SAPI は、当初 PHP 4.2.0 でリリースされましたが、 この時点では実験的なステータスにあったため、 ./configure を実行する際に、明示的に --enable-cli を指定することにより、 有効とする必要がありました。PHP 4.3.0 以降、 CLI SAPI はもはや実験的なステータスではなくなり、 --enable-cli はデフォルトでオンとなりました。 --disable-cli によりこれを無効とする ことも可能です。

PHP 4.3.0 以降、システムにPHPがどのようにインストールされているかによって CLI/CGI バイナリの名前、位置、存在が異なります。デフォルトでは make を実行すると CGI と CLI の両方がビルドされ ソースディレクトリの sapi/cgi/php-cgi と sapi/cli/php にそれぞれ配置されます。両方とも php という名前であることに注意してください make install でどうなるかは configure に因ります。 configure で例えば apxs のような SAPI モジュールが選択された場合、または --disable-cgi が指定された場合、 make install によって CLI が {PREFIX}/bin/php にコピーされます。さもなければ CGI がそこにコピーされます。 既にインストールされている CGI バイナリを上書きしたい場合には、 make install の後に make install-cli を実行してください。あるいは configure で --disable-cgi を指定することもできます。

注意: --enable-cli と --enable-cgi の両方がデフォルトで有効になっています。そのため、configure で --enable-cli を指定したからといって、make install で {PREFIX}/bin/php にコピーされるのが必ずしも CLI になるとは限りません。

PHP 4.2.0 から PHP 4.2.3 までの Windows パッケージでは CLI は CGI php.exe と同じフォルダに php-cli.exe として配布されていました。 PHP 4.3.0 からは Windows パッケージでは CLI は cli という 別のフォルダに php.exe として配布されます。 したがって cli/php.exe となります。 PHP 5 以降、CLI はメインフォルダ内で php.exe という名前で配布されます。CGI バージョンは、php-cgi.exe として配布されます。

PHP 5 では、新しく php-win.exe というファイルが 配布されます。これは CLI バージョンとほぼ同じですが、php-win は何も 出力しないため、コンソールを必要としません（画面に「DOS 窓」が表示 されません）。この振る舞いは、php-gtk と似ています。このためには --enable-cli-win32 オプションを 含めて configure を行います。

注意: 自分の SAPI は何か?
シェルで php -v をタイプすると、 php が CGI なのか CLI なのかわかります。 php_sapi_name() と定数 PHP_SAPI も参照してください。

注意: Unix の man ページが PHP 4.3.2 で追加されました。 シェル環境から man php とすることで見ることができます。

CLI SAPI を他の SAPI と比べた時の 大きな違いを以下に示します。

• CGI SAPI と異なり、ヘッダが出力されません。

  CGI SAPI は HTTP ヘッダの出力を抑制する機能を 提供していますが、等価な機能は CLI SAPI では サポートされていません。

  デフォルトでは CLI は静寂モードで起動されます。古い CGI スクリプトと互換性を 保って使えるように -q スイッチが残されています。

  動作するディレクトリはスクリプトの場所に変更されることはありません （-C および --no-chdir スイッチは 互換性のために残されています）。

  エラーメッセージはプレーンテキストで表示されます （HTML でフォーマットされません）。

• 以下に示すいくつかの php.ini ディレクティブは、CLI SAPI により上書きされます。これは、シェル環境では意味が ないためです。

  上書きされる php.ini のディレクティブ

  ディレクティブ	CLI SAPI のデフォルト値	コメント
  html_errors	FALSE	エラーメッセージに含まれる HTML タグは シェル上では意味がなく、可読性をかなり低下させるため、この ディレクティブはデフォルトで FALSE となっています。
  implicit_flush	TRUE	print(), echo() および 関連するものによる全ての出力は、直ちに出力され、バッファに キャッシュされないことが望ましいと言えます。この場合でも、 標準出力を保留または操作したい場合には、 output buffering を 使用することが可能です。
  max_execution_time	0 (unlimited)	シェル環境では、PHP を際限なく使用できる ようにするために、最大実行時間の制限は無しに設定されています。 Web 用アプリケーションは数秒単位で実行されるよう作られて いますが、シェルアプリケーションの実行時間は、これよりかなり 長くなる傾向があります。
  register_argc_argv	TRUE	CLI SAPI を使用している場合、グローバル PHP 変数 $argc (アプリケーションに渡される引数の数)と $argv (引数の値の配列)は常に登録され、 適切な値が代入されます。 PHP 4.3.0以降、CLI SAPI を使用するときに PHP の $argc 変数と $argv 変数が登録され、適切な値がセットされます。 このバージョンより前では、CGI や MODULE がこれらの変数を生成するには PHP の register_globals ディレクティブがオンになっている必要がありました。 バージョンや register_globals の設定がどうであろうと、 $_SERVER または $HTTP_SERVER_VARS は常に使用可能です。 例：$_SERVER['argv']

  注意: これらのディレクティブは、設定ファイル php.ini またはカスタム 設定ファイル(指定した場合のみ)で他の値に初期化できません。 この制限は、これらのデフォルト値が全ての設定ファイルをパースした後に 適用されるためです。しかし、これらの値は実行時に変更することが 可能です (上記のディレクティブの全てについてこれが当てはまるわけでは ありません。例えば、register_argc_argv)。
  

• シェル環境での動作を容易とするために、以下の定数が定義されています。

  CLI 固有の定数

  定数	説明
  STDIN	stdin へのオープン済みのストリーム。 これにより、以下のようにオープンする必要がなくなります。 <?php $stdin = fopen('php://stdin', 'r'); ?> stdin から1行読み込みたい場合、以下のようにします。 <?php $line = trim(fgets(STDIN)); // STDIN から 1 行読み込む fscanf(STDIN, "%d\n", $number); // STDIN から数値を読み込む ?>
  STDOUT	stdout へのオープン済みのストリーム。 これにより、以下のようにオープンする必要がなくなります。 <?php $stdout = fopen('php://stdout', 'w'); ?>
  STDERR	stderr へのオープン済みのストリーム。 これにより、以下のようにオープンする必要がなくなります。 <?php $stderr = fopen('php://stderr', 'w'); ?>

  上記のように、stderr のようなストリームを自分で オープンする必要はなく、以下のようにストリームリソースの代わりに 定数を使用するだけでかまいません。

  php -r 'fwrite(STDERR, "stderr\n");'

  これらのストリームを明示的に閉じる必要はありません。これは、 PHP により自動的に行われます。

  注意: これらの定数は、PHP スクリプトを stdin から読み込んだ場合は使用できません。
  

• CLI SAPI は、実行されるスクリプトのディレクトリに カレントディレクトリを変更しません !

  CGI SAPI との違いを示す例を以下に示します。

  <?php
// シンプルなテストアプリケーション
echo getcwd(), "\n";
?>

  CGI 版により実行した場合、出力は以下のようになります。

  $ pwd
  /tmp
  
  $ php-cgi -f another_directory/test.php
  /tmp/another_directory
  

  これは、PHP が実行するスクリプトのディレクトリに カレントディレクトリを変更することを明らかに示しています。

  CLI SAPI を使用した場合の出力は次のようになります。

  $ pwd
  /tmp
  
  $ php -f another_directory/test.php
  /tmp
  

  これにより、PHP でシェルツールを書く際の柔軟性をより大きくすることができます。

  注意: CGI SAPI は、この CLI SAPI の動作をコマンドライン実行時のスイッチ -C によりサポートしています。
  

PHP バイナリにより提供されるコマンドラインオプションの一覧は、 -h スイッチを指定して PHP を実行することにより いつでも調べることができます。

Usage: php [options] [-f] <file> [--] [args...]
       php [options] -r <code> [--] [args...]
       php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
       php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
       php [options] -- [args...]
       php [options] -a

  -a               Run interactively
  -c <path>|<file> Look for php.ini file in this directory
  -n               No php.ini file will be used
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -f <file>        Parse and execute <file>.
  -h               This help
  -i               PHP information
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -r <code>        Run PHP <code> without using script tags <?..?>
  -B <begin_code>  Run PHP <begin_code> before processing input lines
  -R <code>        Run PHP <code> for every input line
  -F <file>        Parse and execute <file> for every input line
  -E <end_code>    Run PHP <end_code> after processing all input lines
  -H               Hide any passed arguments from external tools.
  -s               Display colour syntax highlighted source.
  -v               Version number
  -w               Display source with stripped comments and whitespace.
  -z <file>        Load Zend extension <file>.

  args...          Arguments passed to script. Use -- args when first argument
                   starts with - or script is read from stdin

  --ini            Show configuration file names

  --rf <name>      Show information about function <name>.
  --rc <name>      Show information about class <name>.
  --re <name>      Show information about extension <name>.
  --ri <name>      Show configuration for extension <name>.

CLI SAPI は、実行する PHP コードを 取得するために三種類の異なる手段をサポートしています。

1. PHP に特定のファイルの実行を指示する。

   php my_script.php
   
   php -f my_script.php
   

   上記の方法は共に(-f スイッチの使用の如何に関らず) 指定したファイル my_script.php を実行します。 実行ファイルとしてあらゆるファイルを指定することができ、 PHP スクリプトは拡張子 .php で終わる必要がなく、任意の名前や拡張子を 使用することができます。

   注意: -f スイッチを使用している時にスクリプトに引数を渡したい場合は、 最初の引数として -- を渡す必要があります。
   

2. 実行する PHP コードをコマンドラインで直接指定する。

   php -r 'print_r(get_defined_constants());'
   

   シェル変数の置換と引用符の使用については特に注意してください。

   注意: この例をよくみてください。開始/終了タグがありません! -r スイッチを使用した場合、これらのタグは不要と なります。これらのタグを使用するとパーサエラーを発生します。
   

3. 実行する PHP コードを標準入力 (stdin)で指定する。

   これは強力な機能で、以下の(仮想的な)例に示すように、動的に PHP コードを生成し、実行バイナリに入力すること ができます。

   $ some_application | some_filter | php | sort -u >final_output.txt
   

これらのコードを実行する三種類の方法を組み合わせて使用することは できません。

他のシェルアプリケーションのように、PHP バイナリに 引数を指定することができるだけでなく、PHP スクリプトが この引数を取得することも可能です。スクリプトに指定できる 引数の数は PHP による制限を受けません (シェルは指定可能な文字数の最大値を設定しています。通常、この制限値を 越えることはできません)。スクリプトに指定した引数は、グローバル配列 $argv でアクセス可能です。 添字 0 は、常にスクリプト名が含まれています (PHP コードが標準入力またはコマンドラインスイッチ -r により指定された場合、スクリプト名は - となります)。 登録される第 2 のグローバル変数は $argc で (スクリプトに指定された引数の数ではなく )、配列 $argv の要素数が含まれます。

スクリプトに指定する引数が文字 - で始まっていない 限り、特に留意すべきことはありません。スクリプトに指定する引数が文字 - で始まる場合、PHP 自体がこれを パースする必要があるとみなすため、問題を発生します。 これを防止するため、引数リストセパレータ -- を 使用してください。PHP にパースされる引数の後に このセパレータを置くと、その後の全ての引数はそのままパースされずに スクリプトに渡されます。

# これは、指定したコードを実行せずに PHP の使用法を示します
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# これは '-h' を引数として解釈し、PHP の使用法を表示しません
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

また、PHP をシェルスクリプトとして使用する他の手段があります。 最初の行が #!/usr/bin/php で始まり、 PHP の開始/終了タグの中に通常の PHP コードが続くスクリプトを書き、適当なファイル 実行属性を設定する(例: chmod +x test)ことが可能です。 この方法は、通常のシェル/Perl スクリプトと同様に実行することができます。

$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

見て分かるように、- で始まるスクリプトのパラメータを 指定する際に、特に注意する必要はありません。

長いオプション指定は、PHP 4.3.3 以降で利用可能です。

$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

-d configuration_directive[=value]

# 値の部分を省略すると、設定ディレクティブに"1"を指定します
$ php -d max_execution_time
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# 空の値を渡すと設定ディレクティブに""を設定します
php -d max_execution_time=
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# 設定ディレクティブは文字'='の後に指定したものを設定します
$  php -d max_execution_time=20
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php
        -d max_execution_time=doesntmakesense
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328

$ php -v
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies

$ php --ini
Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
Scan for additional .ini files in: (none)
Additional .ini files parsed:      (none)

$ php --rf var_dump
Function [ <internal> public function var_dump ] {

  - Parameters [2] {
    Parameter #0 [ <required> $var ]
    Parameter #1 [ <optional> $... ]
  }
}

$ php --rc Directory
Class [ <internal:standard> class Directory ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [0] {
  }

  - Methods [3] {
    Method [ <internal> public method close ] {
    }

    Method [ <internal> public method rewind ] {
    }

    Method [ <internal> public method read ] {
    }
  }
}

$ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {

  - Functions {
    Function [ <internal> function json_encode ] {
    }
    Function [ <internal> function json_decode ] {
    }
  }
}

$ php --ri date

date

date/time support => enabled
"Olson" Timezone Database Version => 2007.5
Timezone Database => internal
Default timezone => Europe/Oslo

Directive => Local Value => Master Value
date.timezone => Europe/Oslo => Europe/Oslo
date.default_latitude => 59.22482 => 59.22482
date.default_longitude => 11.018084 => 11.018084
date.sunset_zenith => 90.583333 => 90.583333
date.sunrise_zenith => 90.583333 => 90.583333

PHP 実行バイナリは、Web サーバから完全に独立して PHP スクリプトを 実行するために使用することができます。Unix システムを使用している場合、 実行可能とするためには PHP スクリプトの先頭に特別な一行を追加する必要が あります。これにより、システムがそのスクリプトを実行するプログラムを 知ることができます。 Windows 環境では、.php ファイルのダブルクリック オプションに php.exe を関連づけることができます。 または、PHP によりスクリプトを実行するバッチファイルを作成することも 可能です。Unix 上で動作させるためにスクリプトに追加された先頭行は、 Windows 環境での動作に悪影響を与えません。このため、この手法により、 クロスプラットフォーム環境で動作するプログラムを書くことができます。 コマンドライン PHP プログラムの書方の簡単な例を以下に示します。

上のスクリプトでは、特殊な先頭行が用いられており、このファイルが PHP により実行されることを示しています。ここでは CLI 版を使用しているため、 HTTP ヘッダは出力されません。PHP で コマンドラインアプリケーションを使用する際には、2 つの変数 $argc および $argv を使用することが できます。 最初の変数は、引数の数に 1 (実行中のスクリプトの名前)を加えたものです。 2 番目の変数は、引数を保持する配列で、スクリプト名を有する 要素 0 ($argv[0]) から始まっています。

上のプログラムでは、引数が 1 より少ないかまたは多いかを調べています。 また、引数が --help, -help, -h または -? の場合、 ヘルプメッセージを出力し、動的にスクリプト名を出力します。 他の引数を受け取った場合、これを出力します。

上のスクリプトを Unix で実行する場合、実行可能とした後、 script.php echothis または script.php -h とする必要があります。 Windows では、この処理を行なう以下のようなバッチファイルを作成することが できます。

@C:\php\php.exe script.php %1 %2 %3 %4

上のプログラムが script.php という名前であるとし、 c:\php\php.exe に php.exe があるとすると、このバッチファイルは、追加オプション script.bat echothis または script.bat -h を指定して、スクリプトを実行します。

PHP のコマンドラインアプリケーションを拡張するために使用できる その他の関数については、拡張モジュール Readline に関する ドキュメントも参照してください。