PHP で外部スクリプトを安全に実行する方法
Symfony Process に引数配列を渡すと、引数がシェルコマンドとして解釈されることなく、信頼できる外部スクリプトを実行できます。この CLI チュートリアルでは、プロジェクトを作成し、子プロセスの挨拶を取得して、異常終了の報告や遅い子プロセスの停止を行います。子プロセスは実行元アカウントの権限で動作するため、安全な引数処理はサンドボックスの代わりにはなりません。
前提条件
以下のサンプルは、Linux 上の PHP CLI 8.5.10、Composer 2.10.3、Bash 5.3.15、Symfony Process 7.4.19 で再現を確認しています。同じ手順を再現するには、この構成を使用してください。他のランタイムバージョンや Windows での動作は対象外です。PHP 8.5 はアクティブサポート対象の PHP ブランチです。
信頼できる PATH 上の php と composer、書き込み可能な親ディレクトリ、および有効な PHP の
proc_open 関数が必要です。Symfony Process は proc_open を使用して子プロセスを起動します。Composer には、通常必要となる PHP 拡張機能に加え、依存パッケージをダウンロードするためのネットワークアクセスも必要です。
実行側と子スクリプトでは、PHP の -n フラグを使用し、php.ini を無視します。これにより、ローカルの PHP 設定に依存せずに
CLI デモを実行できますが、既存のアプリケーションに推奨する構成ではありません。一方、Composer は通常の PHP 設定で実行します。
環境のセットアップ
プロジェクトを作成するディレクトリで、次のブロックを Bash に貼り付けてください。
(
if [ -n "${COMPOSER:-}" ] || [ -n "${COMPOSER_VENDOR_DIR:-}" ]; then
printf '%s\n' 'Use the default Composer manifest and vendor directory for this example.' >&2
exit 1
fi
mkdir -- php-external-scripts &&
cd -- php-external-scripts &&
export COMPOSER_HOME="$PWD/.composer-home" &&
composer --no-plugins --no-scripts init \
--name=example/php-external-scripts \
--description='PHP child process example' \
--require='symfony/process:7.4.19' \
--no-interaction &&
composer --no-plugins --no-scripts install --no-interaction
)
括弧で囲むことで、ディレクトリの移動と環境の変更をサブシェル内に限定します。依存するコマンドはそれぞれ && で連結しているため、mkdir、cd、または Composer コマンドが失敗すると、セットアップが停止し、誤ったディレクトリで後続の処理が実行されることはありません。成功時も失敗時も、元のシェルは親ディレクトリに留まります。php-external-scripts がすでに存在する場合は、別の親ディレクトリを選んでください。このコマンドを成功させるために既存のプロジェクトを削除しないでください。インストールに失敗すると、新しく作成したディレクトリが残る場合があるため、別の場所で再試行するかを決める前に内容を確認してください。
ローカルの Composer ホームにより、グローバルなプロジェクト設定やプラグインの継承を避け、ガード処理でマニフェストと vendor ディレクトリの上書き指定を拒否します。Composer の install コマンドは、この新しいプロジェクトに composer.lock と vendor/ を作成します。Process のバージョンを固定することで、サンプルの再現性を保っています。アプリケーションで使用する前に、依存パッケージの更新を別途検討してください。
実行するカスタムスクリプトの作成
次の内容を php-external-scripts/hello.php として保存してください。
<?php
$name = $argv[1] ?? 'World';
$mode = $argv[2] ?? 'hello';
if ($mode === 'fail') {
fwrite(STDERR, "Example child failed.\n");
exit(23);
}
if ($mode === 'slow') {
sleep(5);
}
echo "Hello, {$name}!\n";
デフォルトのモードでは挨拶を出力します。他の二つのモードでは、サブプロセスで実際に問題を発生させ、処理を検証します。fail はステータス 23 で終了し、slow は出力を始めるまで五秒間待機します。
PHP からのスクリプト実行
次の内容を php-external-scripts/run-script.php として保存してください。
<?php
use Symfony\Component\Process\Exception\ProcessFailedException;
use Symfony\Component\Process\Exception\ProcessTimedOutException;
use Symfony\Component\Process\Process;
require __DIR__ . '/vendor/autoload.php';
$nameArgument = $argv[1] ?? 'Developer';
$mode = $argv[2] ?? 'hello';
if (!in_array($mode, ['hello', 'fail', 'slow'], true)) {
fwrite(STDERR, "Usage: run-script.php [name] [hello|fail|slow]\n");
exit(64);
}
$process = new Process(
[PHP_BINARY, '-n', __DIR__ . '/hello.php', $nameArgument, $mode],
__DIR__
);
$process->setTimeout(1);
try {
$process->mustRun();
echo $process->getOutput();
} catch (ProcessTimedOutException $exception) {
fwrite(STDERR, "Child exceeded the 1-second timeout.\n");
exit(124);
} catch (ProcessFailedException $exception) {
fwrite(STDERR, sprintf("Child exited with status %d.\n", $process->getExitCode()));
exit(1);
}
PHP_BINARY 定数は、PATH 上で別の php を探すのではなく、この CLI スクリプトを実行している PHP 実行ファイルを選択します。子スクリプトの絶対パスと作業ディレクトリは、呼び出し元の入力ではなく
__DIR__ から取得します。Process のクラスは、Composer のローカルオートローダーから読み込みます。
子プロセスがゼロ以外の終了コードを返すと、mustRun() は ProcessFailedException をスローします。取得した標準出力は、成功した後にのみ出力します。合計実行時間がタイムアウトに達すると、別の ProcessTimedOutException が発生します。このデモでは意図的に一秒という短い制限を設定しているため、実際のタスクでは適切な制限時間を選んでください。
親ディレクトリに留まったまま、次を実行してください。
php -n php-external-scripts/run-script.php
想定される標準出力(終了ステータスは 0):
Hello, Developer!
引数を個別に渡す理由を確認するため、シェル構文を含む名前を渡してください。
php -n php-external-scripts/run-script.php 'Developer; touch SHOULD_NOT_EXIST'
想定される標準出力:
Hello, Developer; touch SHOULD_NOT_EXIST!
セミコロンは名前の一部であり、コマンドの区切りではありません。この呼び出しで SHOULD_NOT_EXIST は作成されません。サンプルを応用する際も、この区別を維持してください。名前をコマンド文字列に連結したり、データを渡すために Process::fromShellCommandline() に切り替えたりしないでください。
実践例
子プロセスの失敗の確認
保存した同じファイルを、失敗モードで実行してください。
php -n php-external-scripts/run-script.php Developer fail
実行側は挨拶を出力せず、次の内容を標準エラー出力に書き込み、ステータス 1 で終了します。
Child exited with status 23.
子プロセスと実行側のステータスは、意図的に異なる値にしています。この CLI ラッパーは、子プロセスのゼロ以外の終了コードをすべて、自身のステータス 1 として報告します。タスクが成功したように扱ったり、子プロセスのエラー出力を呼び出し元に転送したりはしません。
タイムアウトの確認
php -n php-external-scripts/run-script.php Developer slow
実行側は次の内容を標準エラー出力に書き込み、ステータス 124 で終了します。
Child exceeded the 1-second timeout.
Symfony は待機中に合計実行時間のタイムアウトを確認し、この子プロセスの五秒間のスリープが終わる前に停止します。挨拶は出力されません。出力がない子プロセスが必ずしも異常とは限らないため、アイドルタイムアウトは設定しません。
エラー処理とベストプラクティス
セキュリティ上の考慮事項
引数配列は Symfony が推奨するコマンド形式です。この Linux 上の実行経路では、引数はシェル展開を介さずに渡されます。配列の各要素に escapeshellarg() を適用する必要はありません。
これにより、この境界でのシェルインジェクションは防げますが、コマンド実行のリスクがすべて解消されるわけではありません。
- 実行ファイルとスクリプトは、アプリケーションの管理下に置いてください。このサンプルが受け付けるのは挨拶と少数の許可されたモードであり、コマンドやスクリプトのパスではありません。
- 子プログラムに合わせて引数を検証してください。シェルを介さなくても、別のツールでは先頭のハイフンをオプションとして解釈したり、特殊なファイル名構文を認識したりする場合があります。
--は、そのツールのドキュメントでオプション終端マーカーとされている場合にのみ使用してください。 - 信頼できるコードを適切な権限で実行してください。Process は、ファイルシステムへのアクセス、ネットワーク、認証情報を隔離しません。アップロードされたコードなど、信頼できないコードの実行にこのサンプルを使用しないでください。
包括的なエラー処理
二つの catch で、子プロセスの失敗と制限時間の超過を区別します。無効なモードは、子プロセスを起動する前に拒否し、使い方を示すテキストとステータス 64 を返します。依存パッケージやスクリプトが見つからない場合、または proc_open が利用できない場合は、セットアップの問題であり、処理の成功ではありません。
Web アプリケーションでは、例外メッセージ、スタックトレース、取得した子プロセスの出力を公開せず、機密情報を除いた定型のエラーを返してください。サーバー側の診断情報でも機密情報を伏せてください。このチュートリアルはローカルの CLI サンプルであり、PHP-FPM のリクエスト処理は扱いません。
リソース管理
合計実行時間のタイムアウトは、この単純な子プロセスを実行側が待つ時間を制限します。メモリや出力サイズの制限ではなく、任意のプログラムが子孫プロセスや不完全なファイルを残さないという保証でもありません。挨拶の出力は少量に留まります。大量の出力を生成するプログラムには、ストリーミングや出力量の制限を別途設計する必要があります。
永続的なバックグラウンド処理には、ジョブキューやサービススーパーバイザーを使用してください。Process のドキュメントの説明のとおり、プロセスを非同期で起動しても、親プロセスの終了後に存続するとは限りません。画像変換やスケジュールされたジョブには、それぞれ入力、出力、デプロイのポリシーが必要です。このチュートリアルでは、それらのワークフローは提供しません。
まとめ
hello.php を実際のタスクに置き換える前に、受け付ける引数、成功の定義、失敗やタイムアウトの後に行う処理を決めてください。安全なクォート処理だけでセキュリティポリシーが完成すると考えず、これらの検証を引数配列と併せて維持してください。
