【PHP8.x】shell_exec()関数の使い方

Copy
1<?php
2
3/**
4 * shell_exec() と exec() の違いをデモンストレーションします。
5 *
6 * shell_exec(): コマンドの完全な出力を文字列として返します。
7 *               実行に失敗した場合や機能が無効な場合は null を返します。
8 * exec(): コマンドの出力の最後の行を返します。
9 *         オプションで、出力の全行を配列として第2引数に格納します。
10 *         オプションで、コマンドの終了ステータスを第3引数に格納します。
11 *         実行に失敗した場合や機能が無効な場合は false を返します。
12 */
13function demonstrateShellExecAndExecDifference(): void
14{
15    // 実行するコマンドを定義
16    // 'ls -l' は現在のディレクトリのファイルとディレクトリを詳細表示します。
17    // このコマンドの出力は、PHPが実行される環境 (例: Linux, Windows) や、
18    // 現在のディレクトリの内容によって異なります。
19    $command = 'ls -l';
20
21    echo "--- shell_exec() の例 ---\n";
22    // shell_exec() を使用してコマンドを実行
23    // コマンドの標準出力全体を文字列として取得します。
24    $shellExecOutput = shell_exec($command);
25
26    if ($shellExecOutput === null) {
27        echo "shell_exec(): コマンドの実行に失敗したか、PHPのセキュリティ設定 (disable_functions) 等により利用できません。\n";
28    } else {
29        echo "shell_exec() の出力 (文字列):\n";
30        echo $shellExecOutput; // 出力全体が単一の文字列として表示される
31    }
32    echo "\n";
33
34    echo "--- exec() の例 ---\n";
35    $execOutputLines = []; // 出力の各行を格納する配列
36    $execReturnStatus = -1; // コマンドの終了ステータスを格納する変数
37
38    // exec() を使用してコマンドを実行
39    // 戻り値は出力の最後の行です。
40    // 第2引数 ($execOutputLines) には出力の全行が配列として格納されます。
41    // 第3引数 ($execReturnStatus) にはコマンドの終了ステータスが格納されます。
42    $lastLine = exec($command, $execOutputLines, $execReturnStatus);
43
44    if ($lastLine === false) {
45        echo "exec(): コマンドの実行に失敗したか、PHPのセキュリティ設定 (disable_functions) 等により利用できません。\n";
46    } else {
47        echo "exec() の戻り値 (最後の行):\n";
48        echo $lastLine . "\n"; // 最後の行のみが表示される
49
50        echo "\nexec() の第2引数 (全行の配列):\n";
51        if (empty($execOutputLines)) {
52            echo "  出力がありません。\n";
53        } else {
54            foreach ($execOutputLines as $line) {
55                echo "  " . $line . "\n"; // 配列として格納された全行が表示される
56            }
57        }
58
59        echo "\nexec() の第3引数 (終了ステータス):\n";
60        echo "  " . $execReturnStatus . "\n"; // コマンドの終了ステータス (通常、成功なら0)
61    }
62    echo "\n";
63}
64
65// 関数を呼び出してデモンストレーションを実行
66demonstrateShellExecAndExecDifference();
67

PHPのshell_exec関数とexec関数は、PHPスクリプトの中からOSのコマンド（例: ls -lなど）を実行し、その結果を取得するために利用されます。

shell_exec関数は、引数として指定されたコマンドを実行し、その標準出力の「すべて」を単一の文字列として返します。コマンドの実行に失敗したり、PHPのセキュリティ設定（disable_functionsなど）により利用できない場合はnullが戻り値となります。

一方、exec関数は、引数で指定されたコマンドを実行し、その標準出力の「最後の行」を文字列として返します。さらに、第2引数に空の配列を渡すと、コマンドの標準出力の「全行」がその配列の各要素として格納されます。また、第3引数に整数型変数を渡せば、実行されたコマンドの終了ステータス（通常、成功時は0）も取得できます。execがコマンドの実行に失敗したり、利用できない場合はfalseを返します。

このように、両関数は外部コマンドを実行する点で共通していますが、出力の取得形式や追加情報の取得方法、失敗時の戻り値が異なりますので、用途に応じて適切な関数を選択してください。

Copy
1<?php
2
3/**
4 * shell_exec 関数を使用してシステムコマンドを実行し、その結果を初心者にもわかりやすく表示します。
5 * 'permission denied' のような権限関連の問題が発生した場合の挙動についても説明します。
6 *
7 * @param string $command 実行するシェルコマンド。
8 * @return void
9 */
10function executeAndDisplayShellCommand(string $command): void
11{
12    echo "Attempting to execute command: '$command'\n";
13    echo "---------------------------------------------------\n";
14
15    // shell_exec はコマンドの標準出力を文字列として返します。
16    // コマンドの実行に失敗した場合（例: コマンドが見つからない）、
17    // または shell_exec 関数自体がPHPの設定で無効化されている場合は null を返します。
18    $output = shell_exec($command);
19
20    if ($output === null) {
21        // null が返された場合、コマンドの実行に根本的な問題があった可能性が高いです。
22        // 主な原因として、以下の点が考えられます。
23        // 1. 指定したコマンドが見つからない (例: PATHが通っていない、コマンド名が間違っている)。
24        // 2. PHPプロセスがそのコマンドを実行する権限を持っていない ('permission denied')。
25        //    例: PHPが実行されているWebサーバーユーザーが、特定のシステムコマンドやスクリプトを実行する権限がない場合。
26        // 3. PHPの設定ファイル (php.ini) で shell_exec 関数が disable_functions ディレクティブにより無効化されている。
27        echo "Error: Command execution failed or shell_exec is disabled.\n";
28        echo "  Possible causes:\n";
29        echo "    - The command '$command' was not found.\n";
30        echo "    - 'Permission denied': The PHP process (e.g., web server user) does not have permission to execute the command.\n";
31        echo "    - The 'shell_exec' function is disabled in php.ini (check 'disable_functions').\n";
32        echo "  Please check your web server error logs and PHP error logs for more detailed information.\n";
33    } elseif ($output === '') {
34        // 空文字列が返された場合、コマンド自体は実行されたが、
35        // 標準出力に何も出力しなかったか、エラーメッセージを標準エラー出力に出力した可能性があります。
36        // 'permission denied' のようなエラーがコマンドの内部で発生し、そのメッセージが標準エラーに出力され、
37        // 標準出力が空のままだったケースも考えられます。
38        echo "Command executed successfully, but produced an empty output (no standard output).\n";
39        echo "  Possible reasons:\n";
40        echo "    - The command completed its task without printing anything to standard output.\n";
41        echo "    - An internal error (e.g., 'permission denied' within the command's operation) occurred, and its message was sent to standard error (stderr), which shell_exec does not capture.\n";
42        echo "  Consider using `exec` or `proc_open` if you need to capture stderr.\n";
43    } else {
44        // コマンドが正常に実行され、標準出力があった場合。
45        echo "Command output successfully captured:\n";
46        echo $output;
47    }
48    echo "---------------------------------------------------\n\n";
49}
50
51// --------------------------------------------------------------------------------
52// サンプルコマンドの実行例
53// --------------------------------------------------------------------------------
54
55// 例1: 正常に動作する可能性のあるコマンド (現在のディレクトリの内容をリスト表示)
56// 多くのLinux/macOS環境で動作し、PHPプロセスが実行権限を持つことを想定しています。
57executeAndDisplayShellCommand('ls -l');
58
59// 例2: 存在しないコマンドを実行しようとした場合
60// (通常、PHPの実行環境によって null を返すか、空の出力を返します)
61executeAndDisplayShellCommand('non_existent_command_123xyz');
62
63// 例3: PHPプロセスが実行されているユーザー名を表示するコマンド
64// これは直接 'permission denied' を引き起こすわけではありませんが、
65// PHPがどのユーザー権限で動作しているかを理解するのに役立ちます。
66// 特定の操作で 'permission denied' が発生する場合、このユーザーがその操作に必要な権限を持っているか確認します。
67executeAndDisplayShellCommand('whoami');
68
69// 注意: 意図的に 'permission denied' を発生させるコマンドの例は、
70//       実行環境に大きく依存し、セキュリティリスクを伴う可能性があるため、このコードには含めません。
71//       しかし、例えばPHPが書き込み権限を持たないディレクトリにファイルを作成しようとするコマンド
72//       (例: 'touch /root/somefile.txt' や 'echo "test" > /var/www/unwritable_dir/file.txt')
73//       を実行した場合に、上記の $output === null または $output === '' のケースに該当することがあります。

PHP 8のshell_exec関数は、PHPスクリプト内からシステムコマンドを実行し、その標準出力を文字列として取得する機能です。引数$commandには実行したいシェルコマンドを文字列で指定します。コマンドが正常に実行されれば、その結果の出力が文字列として返されますが、実行に失敗した場合にはnullが返されます。

nullが返される主な原因としては、指定されたコマンドが見つからない、またはPHPが動作しているユーザーアカウントにそのコマンドを実行する権限がない「permission denied」のような状況が考えられます。特にWebサーバー環境では、セキュリティ上の理由からPHPの実行権限が制限されていることが多く、この権限不足が問題となることがあります。また、PHPの設定ファイル（php.ini）でshell_exec関数自体が無効化されている可能性もあります。

もし空文字列が返された場合は、コマンド自体は実行されたものの、標準出力に何も表示しなかったか、エラーメッセージが標準エラー出力に送られた可能性があります。「permission denied」のようなエラーがコマンド内部で発生し、そのメッセージが標準エラーに出力され、shell_execがそれをキャプチャできない場合もこれに該当します。

問題が発生した際には、WebサーバーのエラーログやPHPのエラーログを確認し、PHPがどのユーザー権限で動作しているか（例えばwhoamiコマンドで確認できます）を把握した上で、そのユーザーが必要な実行権限を持っているか確認することが重要です。

Copy
1<?php
2
3/**
4 * リモートサーバーでSSH経由でコマンドを実行し、その標準出力を取得します。
5 *
6 * この関数は、SSH接続情報（ユーザー、ホスト、秘密鍵など）が事前に設定され、
7 * パスワード入力なしでSSH接続ができる環境で動作することを想定しています。
8 *
9 * @param string $username SSH接続に使用するユーザー名
10 * @param string $hostname SSH接続先のホスト名またはIPアドレス
11 * @param string $remoteCommand リモートサーバーで実行するコマンド
12 * @return string|null コマンドの標準出力、またはコマンドの実行に失敗した場合は null
13 */
14function executeSshCommand(string $username, string $hostname, string $remoteCommand): ?string
15{
16    // SSHコマンドを構築します。
17    // -o BatchMode=yes: パスワードや対話的なプロンプトを無効にし、スクリプトからの実行に適しています。
18    // -o StrictHostKeyChecking=no: 初めて接続するホストでも確認なしで接続を許可します。
19    //    セキュリティリスクがあるため、本番環境ではこのオプションを削除し、事前にホスト鍵を登録してください。
20    // escapeshellarg() を使用して、コマンド引数を安全にエスケープします。
21    $command = sprintf(
22        "ssh -o BatchMode=yes -o StrictHostKeyChecking=no %s@%s '%s'",
23        escapeshellarg($username),
24        escapeshellarg($hostname),
25        escapeshellarg($remoteCommand)
26    );
27
28    // shell_exec を使用して外部コマンドを実行し、その標準出力を取得します。
29    // コマンドが失敗した場合、または出力がない場合は null を返します。
30    $output = shell_exec($command);
31
32    return $output;
33}
34
35// --- サンプル使用例 ---
36// 以下のプレースホルダーを実際の環境に合わせて変更してください。
37// 例: SSHキーが設定され、パスワードなしで接続できるリモートサーバー
38$sshUser = 'your_ssh_user';           // リモートサーバーのユーザー名
39$sshHost = 'your_remote_server_ip';   // リモートサーバーのIPアドレスまたはホスト名
40$commandToExecute = 'echo "Hello from remote server $(hostname)"'; // リモートで実行したいコマンド
41
42echo "SSH経由でリモートコマンドを実行中...\n";
43
44$result = executeSshCommand($sshUser, $sshHost, $commandToExecute);
45
46if ($result !== null) {
47    echo "--- SSHコマンドの出力 ---\n";
48    echo $result;
49    echo "---------------------------\n";
50} else {
51    echo "SSHコマンドの実行に失敗しました。以下の点を確認してください:\n";
52    echo "1. リモートサーバーへのSSH接続が可能であるか。\n";
53    echo "2. 指定したユーザー名とホスト名が正しいか。\n";
54    echo "3. パスワードなしでSSH接続できる設定になっているか（例: 公開鍵認証）。\n";
55    echo "4. リモートで実行しようとしたコマンドが正しいか。\n";
56}
57

PHPのshell_exec関数は、OSのシェルで任意のコマンドを実行し、その標準出力を取得する機能を提供します。このサンプルコードは、shell_execを活用してSSH経由でリモートサーバー上のコマンドを実行し、その結果を受け取る方法を具体的に示しています。

executeSshCommand関数は、SSH接続に使用するユーザー名、ホスト名、そしてリモートで実行したいコマンドを引数として受け取ります。関数内では、これらの引数をescapeshellargで適切にエスケープし、安全なSSHコマンド文字列を構築しています。escapeshellargは、シェルコマンドの引数として渡される文字列に含まれる特殊文字を無害化し、悪意のあるコマンドインジェクションを防ぐための重要なセキュリティ対策です。構築されたコマンドはshell_execに渡され、リモートサーバー上で実行されます。

この機能を使うには、事前にSSHの公開鍵認証を設定するなど、パスワード入力なしでリモートサーバーに接続できる環境が必要です。コード内の-o StrictHostKeyChecking=noオプションは、初回接続時のホスト鍵の確認をスキップしますが、セキュリティリスクがあるため本番環境での使用は避け、ホスト鍵を事前に登録することが推奨されます。shell_execはコマンドの標準出力を文字列として返し、コマンドの実行に失敗した場合や出力がない場合はnullを返します。これにより、PHPアプリケーションから外部システムを連携・制御することが可能になります。

Copy
1<?php
2
3/**
4 * shell_exec 関数を使用して外部コマンドを実行し、結果を表示するサンプル関数。
5 * コマンドが「実行されない」ケースや、その結果のハンドリングを示します。
6 *
7 * システムエンジニアを目指す初心者向けに、shell_exec が null や空文字列を返す原因と
8 * 考えられる対策をコメントで補足しています。
9 */
10function demonstrateShellExec(): void
11{
12    echo "--- shell_exec のデモンストレーション ---" . PHP_EOL . PHP_EOL;
13
14    // 1. 成功する可能性が高いシンプルなコマンドの例
15    echo "--- 1. 成功する可能性が高いコマンドの例 (現在のディレクトリの内容を表示) ---" . PHP_EOL;
16    // OSに応じてコマンドを切り替える (Windows: dir, Linux/macOS: ls -la)
17    $command1 = (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') ? 'dir' : 'ls -la';
18    echo "実行コマンド: '{$command1}'" . PHP_EOL;
19
20    // shell_exec を実行
21    $output1 = shell_exec($command1);
22
23    if ($output1 === null) {
24        // null が返された場合、コマンド実行自体に失敗した可能性が高い
25        echo "結果: null が返されました。コマンドの実行に失敗したか、shell_exec が無効化されている可能性があります。" . PHP_EOL;
26        echo "考えられる主な原因:" . PHP_EOL;
27        echo "  - PHPの設定 (php.ini) で shell_exec が disable_functions に指定されている。" . PHP_EOL;
28        echo "  - コマンド '{$command1}' が見つからない、またはパスが通っていない。" . PHP_EOL;
29        echo "  - PHP実行ユーザーにコマンドの実行権限がない。" . PHP_EOL;
30    } else {
31        echo "結果 (成功):" . PHP_EOL;
32        echo $output1 . PHP_EOL;
33    }
34    echo PHP_EOL;
35
36    // 2. 存在しないコマンドの例 (「実行されない」またはエラーになるケース)
37    echo "--- 2. 存在しないコマンドの例 (実行されない、またはエラーになるケース) ---" . PHP_EOL;
38    // 存在しない可能性が高いコマンドを指定
39    $command2 = 'this_nonexistent_command_123456789';
40    echo "実行コマンド: '{$command2}'" . PHP_EOL;
41
42    $output2 = shell_exec($command2);
43
44    if ($output2 === null) {
45        // null が返された場合、存在しないコマンドのため実行自体がOSレベルで失敗した可能性が高い
46        echo "結果: null が返されました。コマンドの実行に失敗したか、shell_exec が無効化されている可能性があります。" . PHP_EOL;
47        echo "考えられる主な原因:" . PHP_EOL;
48        echo "  - コマンド '{$command2}' が見つからない、またはパスが通っていない。(このケースではこれに該当)" . PHP_EOL;
49        echo "  - PHPの設定 (php.ini) で shell_exec が disable_functions に指定されている。" . PHP_EOL;
50        echo "  - PHP実行ユーザーにコマンドの実行権限がない。" . PHP_EOL;
51    } else if (empty($output2)) {
52        // 空文字列が返された場合、コマンド自体は実行されたものの、標準出力がなかった可能性
53        // エラーメッセージが標準エラー出力に出力され、shell_exec では捕捉できなかったケースが多い
54        echo "結果: 空文字列が返されました。コマンドは実行されたが、標準出力がなかった可能性があります。" . PHP_EOL;
55        echo "  (例: コマンドは存在するが引数が不正でエラーメッセージが標準エラー出力に出力された場合)" . PHP_EOL;
56        echo "  コマンドが実際に実行されたかどうかは、他の方法で確認する必要があります（例: ファイル作成、ログ出力など）。" . PHP_EOL;
57    } else {
58        // 予想外に何か出力があった場合
59        echo "結果 (予想外の成功):" . PHP_EOL;
60        echo $output2 . PHP_EOL;
61    }
62    echo PHP_EOL;
63
64    // 3. エラーになるコマンドの例（shell_exec は標準エラー出力を捕捉しないため、結果は空になりがち）
65    echo "--- 3. エラーが発生するコマンドの例 (標準エラー出力は取得できないため、結果は空になりがち) ---" . PHP_EOL;
66    // 存在しないファイルを cat/type しようとする例
67    $command3 = (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') ? 'type non_existent_file_xyz.txt' : 'cat non_existent_file_xyz.txt';
68    echo "実行コマンド: '{$command3}'" . PHP_EOL;
69
70    $output3 = shell_exec($command3);
71
72    if ($output3 === null) {
73        // null が返された場合、コマンド実行自体に失敗した可能性
74        echo "結果: null が返されました。コマンドの実行に失敗したか、shell_exec が無効化されている可能性があります。" . PHP_EOL;
75        echo "考えられる主な原因:" . PHP_EOL;
76        echo "  - コマンド '{$command3}' が見つからない、またはパスが通っていない。" . PHP_EOL;
77        echo "  - PHPの設定 (php.ini) で shell_exec が disable_functions に指定されている。" . PHP_EOL;
78        echo "  - PHP実行ユーザーにコマンドの実行権限がない。" . PHP_EOL;
79    } else if (empty($output3)) {
80        // 空文字列が返された場合、コマンドは実行されたが、エラーメッセージは標準エラー出力に出力された可能性が高い
81        echo "結果: 空文字列が返されました。コマンドは実行されたが、エラーメッセージは標準エラー出力に出力されたため、" . PHP_EOL;
82        echo "  shell_exec では捕捉できませんでした。コマンドが正常終了しなかった可能性が高いです。" . PHP_EOL;
83    } else {
84        // 予想外に何か出力があった場合 (例: エラーメッセージが標準出力に出力されるコマンド)
85        echo "結果 (成功):" . PHP_EOL;
86        echo $output3 . PHP_EOL;
87    }
88    echo PHP_EOL;
89
90    echo "--- shell_exec のデモンストレーション終了 ---" . PHP_EOL;
91    echo "補足: shell_exec はコマンドの標準出力のみを返します。より詳細なエラー情報を取得したい場合（標準エラー出力や終了ステータス）、" . PHP_EOL;
92    echo "passthru(), exec(), proc_open() などの他の関数を検討してください。" . PHP_EOL;
93}
94
95// 関数を実行します
96demonstrateShellExec();

PHP 8のshell_exec関数は、指定された外部コマンドをシステムシェルを通じて実行し、その結果の標準出力を文字列として取得する機能です。引数$commandには、OSのコマンドプロンプトで実行するのと同様のコマンド文字列を渡します。

コマンドが正常に実行され、標準出力がある場合は、その出力内容が文字列で返されます。しかし、shell_execがnullを返した場合、これはコマンドの実行自体がシステムレベルで「実行されない」状態にあることを示します。この主な原因としては、PHPの設定ファイル（php.ini）でshell_execがセキュリティ上の理由から無効化されている、指定したコマンドが見つからない（パスが通っていない）、またはPHPが動作しているユーザーにそのコマンドを実行する権限がない、といった状況が考えられます。

また、コマンドは実行されたものの、標準出力が一切なかった場合は空の文字列が返されます。このケースでは、例えばコマンド自体は存在しても引数が不正でエラーが発生し、そのエラーメッセージが標準エラー出力に出力されたため、shell_execでは捕捉できないという状況がよくあります。

shell_execは標準出力のみを扱うため、コマンドの終了ステータスや標準エラー出力を詳細に確認したい場合は、passthru、exec、proc_openといった別のPHP関数を検討することをお勧めします。