【PHP】LaravelのProcessファサードで外部コマンドを実行する方法

Laravel 13.x の Process ファサードは、Symfony の Process コンポーネントを薄い API で包んだものです。外部の OS コマンドを実行し、終了を待つことも、非同期に始めることもできます。この記事の対象は Laravel 13.x と PHP 8.3 以上です。検証の記録では、laravel/laravel v13.11.0(laravel/framework v13.42.0、PHP 8.4.27、Composer 2.10.3)の新規アプリケーションで確認しています。PHP 8.3 だけの実行ログは、この検証には含まれていません。

ここでの話は、OS の外部コマンドを走らせることです。Artisan コマンドクラスを自作する手順とは別で、そちらは LaravelでArtisanコマンドを自作する方法 を参照してください。

プロセスを実行する

Process::run() はプロセスを起動し、終了まで待ちます。Process::start() は非同期に始めます。

use Illuminate\Support\Facades\Process;

$result = Process::run(['php', '-r', 'echo "hello-run";']);

$result->successful(); // true
$result->failed();     // false
$result->exitCode();   // 0
$result->output();     // hello-run
$result->seeInOutput('hello-run'); // true
$result->command();    // 空ではありません

検証では、上記の run は終了コード 0 で、出力は hello-run でした。Process::start(['sleep', '1']) は、実行中に running() が true、id() が整数を返し、wait() のあとに成功しました。

結果オブジェクト(ProcessResult)には、ほかに errorOutput()、seeInErrorOutput()、throw()、throwIf($condition) があります。プロセスが失敗したとき(throwIf は条件が true のときだけ)、Illuminate\Process\Exceptions\ProcessFailedException を投げます。検証では、php -r で exit(2) したプロセスの seeInErrorOutput('err-ok') が一致し、throwIf(false) は同じ結果を返し、throwIf(true) と throw() は例外を投げました。

引数の渡し方(配列と文字列)

コマンドの渡し方で、Laravel が Symfony の Process を組み立てる経路が分かれます。laravel/framework v13.42.0 の PendingProcess::toSymfonyProcess() は、次のとおりです。

$process = is_iterable($command)
    ? new Process($command, null, $this->environment)
    : Process::fromShellCommandline((string) $command, null, $this->environment);
  • 配列(または iterable): new Symfony\Component\Process\Process($command, …) です。コマンドラインは argv として渡り、シェルは介しません。
  • 文字列: Process::fromShellCommandline((string) $command, …) です。Symfony の説明では、OS のシェル(Unix では /bin/sh)がコマンドラインを解釈します。

この分岐で、Laravel は配列側を escapeshellarg() で包んではいません。配列形式はシェルを避ける経路です。

信頼できない値を文字列コマンドへ連結すると、シェルがメタ文字を解釈します。検証では、$payload に ; touch …/pwned のような値を入れ、次を比べました。

Process::run(['echo', 'start'.$payload]);
Process::run('echo start'.$payload);

配列形式は終了コード 0 で、出力はリテラルの start; touch …/pwned になり、ファイルは作られませんでした。文字列へ連結した形式も終了コード 0 でしたが、出力は start になり、ファイルは作られました(検証後に削除しています)。

「配列なら常に安全」「文字列なら常に危険」とは言い切れません。問題になるのは、信頼できない値を文字列コマンドに連結したときです。

ドキュメントの導入例には Process::run('ls -la') のような文字列もあります。配列形式は、主にアサーションの節で説明されています。ここで書いた分岐は、ソースと上記の実演の範囲です。

作業ディレクトリ、標準入力、出力の抑制

path() は作業ディレクトリを指定します(指定しなければ、実行中の PHP スクリプトのカレントディレクトリです)。input() は標準入力を渡します。quietly() は出力の取得を止め、その後の output() は空文字になります。

Process::path($directory)->run(['pwd']);

Process::input('hello-input-1117')->run(['cat']);
// 出力は hello-input-1117

Process::quietly()->run(['php', '-r', 'echo "hello-quietly";']);
// 成功し、output() は空文字

タイムアウト

デフォルトのタイムアウトは 60 秒です(PendingProcess の $timeout = 60)。timeout() と idleTimeout() は秒の整数、または CarbonInterval を受け取ります。forever() はタイムアウトを null にします。制限を超えると Illuminate\Process\Exceptions\ProcessTimedOutException を投げます。

use Carbon\CarbonInterval;
use Illuminate\Process\Exceptions\ProcessTimedOutException;

Process::timeout(1)->run(['sleep', '3']); // ProcessTimedOutException

Process::timeout(10)->idleTimeout(1)->run(['sleep', '3']); // ProcessTimedOutException

Process::timeout(CarbonInterval::seconds(30))
    ->run(['php', '-r', 'echo "interval-ok";']); // 成功、出力は interval-ok

forever() については、Process::fake() と assertRan の組み合わせで、タイムアウトが null になることを確認しています。start() のあとの非同期タイムアウト自体は、この検証では実行していません。詳細は Processes – Laravel 13.x のタイムアウトの節を見てください。

環境変数

env($array) は、起動するプロセスへ環境変数を足します(親の環境も引き継ぎます)。値が false のときは、同名の引き継いだ変数を除きます。検証では、ダミー名 LARA_PROCESS_VERIFY_DUMMY だけを使っています。

Process::env(['LARA_PROCESS_VERIFY_DUMMY' => 'verify-ok-1117'])
    ->run(['php', '-r', 'echo getenv("LARA_PROCESS_VERIFY_DUMMY");']);
// 出力は verify-ok-1117

Process::env(['LARA_PROCESS_VERIFY_DUMMY' => false])
    ->run(['php', '-r', 'var_export(getenv("LARA_PROCESS_VERIFY_DUMMY"));']);
// 親で同名の変数を出していた場合、子の出力は false

Process::pipe() と並行実行

Process::pipe() は複数のコマンドを同期的につないで実行し、最後のプロセスの ProcessResult を返します。クロージャ、またはコマンド文字列の配列を渡せます。検証では、次の配列で成功し、出力に hello-pipe が含まれていました。

$result = Process::pipe([
    'php -r "echo \"hello-pipe\";"',
    'cat',
]);

並行に非同期プロセスを走らせるには pool() または concurrently() を使います。プールの項目は as() で名前を付けられ、wait() はキーごとの結果を返します。concurrently() はプールを始めてすぐ待ち、配列の分割代入が使えます。

$pool = Process::pool(function ($pool) {
    $pool->as('one')->command(['php', '-r', 'echo "pool-one";']);
    $pool->as('two')->command(['php', '-r', 'echo "pool-two";']);
})->start();

$results = $pool->wait();
$results['one']->output(); // pool-one
$results['two']->output(); // pool-two

[$first, $second] = Process::concurrently(function ($pool) {
    $pool->command(['php', '-r', 'echo "conc-a";']);
    $pool->command(['php', '-r', 'echo "conc-b";']);
});

非同期プロセス、プロセス ID、シグナル

非同期の InvokedProcess には id()、signal($sig)、running()、wait()、waitUntil($callback)、output()、errorOutput()、latestOutput()、latestErrorOutput() があります。waitUntil はコールバックが true を返したときに戻るため、その時点ではまだ実行中のことがあります。検証では、「READY」を出力するプロセスに対し、そのあと改めて wait() して成功を確認しました。

start(['sleep', '5']) の実行中、id() は整数でした。signal(SIGTERM) のあと wait() すると、終了コードは 143(128+15)で、failed() は true でした。プールでも signal(SIGTERM) のあとの終了コードは 143 でした。

latestErrorOutput() は、describe() で作ったフェイクのプロセスで確認しています。長時間の実プロセスの標準エラーを測ったものではありません。

テストでのフェイク

Process::fake() は、テスト中のプロセス呼び出しをスタブします。検証は PHPUnit の Feature テストで行っています。公式ドキュメントには Pest のタブもありますが、この 13.x スケルトン(laravel/laravel v13.11.0)には Pest が入っておらず、Pest は追加していません。テスト全般は Laravelでテストを実装する方法 も参照してください。

Process::result() はスタブの結果を組み立てます。文字列だけを渡すと、出力だけのスタブになります。sequence() は、同じコマンドへ結果を順に割り当てます。describe() は非同期の経過(出力、エラー出力、終了コード、イテレーション)をフェイクします。

Process::fake([
    'php -r "echo 1;"' => Process::result(output: 'fake-one'),
    'php -r "echo 2;"' => Process::result(output: 'fake-two'),
]);

$one = Process::run('php -r "echo 1;"');
$one->seeInOutput('fake-one'); // true

フェイク結果の文字列には、末尾の改行が付くことがあります。厳密な一致ではなく、seeInOutput で比べてください。

文字列で指定したフェイクのパターンは、配列形式の呼び出しを自動では捕まえません。検証では、文字列キー 'php artisan migrate' を登録した Process::fake() が、Process::run(['php', 'artisan', 'migrate']) を捕まえず、検証用アプリケーションで本物の migrate が実行されました。配列で呼び出したときのコマンドラインは、配列のまま照合するか、ワイルドカードを使います。

Process::fake([
    '*' => Process::sequence()
        ->push(Process::result('First invocation'))
        ->push(Process::result('Second invocation')),
]);

Process::run(['php', '-r', 'echo "seq-a";']);
Process::assertRan(['php', '-r', 'echo "seq-a";']);

ドキュメントに載っているアサーションは assertRan、assertDidntRun、assertRanTimes、assertRanInOrder です。コマンド文字列、引数の配列、クロージャを渡せます。laravel/framework v13.42.0 では、assertDidntRun() は assertNotRan() のエイリアスで、どちらも同じ動きをします。ドキュメントの見出しは assertDidntRun です。assertNothingRan() も Factory にあり、呼び出しを一度もしていない状態で確認できますが、processes.md の見出しではありません。

preventStrayProcesses() を使うと、一致するフェイクが無い呼び出しは RuntimeException になります。検証では、Process::fake(['ls *' => 'Test output...']) のあと、ls -la は通り、bash import.sh は例外になりました。

TTY モード

ドキュメントには tty() があり、TTY モードは Windows ではサポートされないこと、vim のように実ターミナルが必要なプロセス向けであることが注意として書かれています。laravel/framework v13.42.0 では tty() と supportsTty() があり、Process::tty() で tty プロパティが true になることは確認しています。実ターミナルを使った実行は、この検証では行っていません。

まとめ

  • Laravel 13.x の Process ファサードは、Symfony Process の薄い API です。対象は PHP 8.3 以上です
  • Process::run() は終了まで待ち、Process::start() は非同期に始めます
  • 配列(iterable)は argv として渡り、シェルを介しません。文字列は OS のシェルが解釈します
  • 信頼できない値を文字列コマンドに連結すると、シェルがメタ文字を解釈することがあります
  • デフォルトのタイムアウトは 60 秒です。同期の timeout / idleTimeout 超過は ProcessTimedOutException になります
  • テストでは Process::fake() を使えます。文字列のフェイクキーは、配列形式の呼び出しを自動では捕まえません

外部コマンドの実行を含む既存アプリケーションの保守を進めたい場合は、当社(ノマドシステム工房)の保守・バージョンアップ診断もあります。

出典

コメントする