proc_open

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

proc_open 执行一个命令,并且打开用来输入/输出的文件指针。

说明

proc_open(
    mixed $cmd,
    array $descriptorspec,
    array &$pipes,
    string $cwd = null,
    array $env = null,
    array $other_options = null
): resource

类似 popen() 函数, 但是 proc_open() 提供了更加强大的控制程序执行的能力。

参数

cmd

string 形式执行的命令行。特殊字符必须经过转义,并且使用正确的引号。

注意: Windows 上, 除非在 other_options 中 把 bypass_shell 设置为 true ,否则 cmd 会被传递给 cmd.exe (实际上是 %ComSpec%) 其中的 /c 标志是 未加引号的 字符串 (也就是和 proc_open() 一样)。 这可能会导致 cmd.exe 删除 cmd 中的引号 (详见 cmd.exe 文档), 从而导致意外的,甚至是潜在的危险行为,因为 cmd.exe 错误消息可能包含 (部分) 传递的 cmd (见下面的例子)。

从 PHP 7.4.0 开始,cmd 参数可以使用 array 类型传递。 在这种情况下,进程将直接打开(不通过 shell )。 而 PHP 会处理任何必要的参数转义。

注意:

在 Windows 上, array 元素的参数转义假定 执行命令的命令行解析与 VC 运行时进行的命令行参数解析兼容。

descriptorspec

一个索引数组。 数组的键表示描述符,数组元素值表示 PHP 如何将这些描述符传送至子进程。 0 表示标准输入(stdin),1 表示标准输出(stdout),2 表示标准错误(stderr)。

数组中的元素可以是:

  • 包含了要传送至进程的管道的描述信息的数组。 第一个元素为描述符类型, 第二个元素是针对该描述符的选项。 有效的类型有:pipe (第二个元素可以是: r 向进程传送该管道的读取端,w 向进程传送该管道的写入端), 以及 file(第二个元素为文件名)。
  • 表达一个真实文件描述符的流资源类型 (例如:已打开的文件,一个 socket 端口,STDIN)。

文件描述符的值不限于 0,1 和 2,你可以使用任何有效的文件描述符 并将其传送至子进程。 这使得你的脚本可以和其他脚本交互操作。 例如,可以通过指定文件描述符将密码以更加安全的方式 传送至诸如 PGP,GPG 和 openssl 程序, 同时也可以很方便的获取这些程序的状态信息。

pipes

将被置为索引数组, 其中的元素是被执行程序创建的管道对应到 PHP 这一端的文件指针。

cwd

要执行命令的初始工作目录。 必须是 绝对 路径, 设置此参数为 null 表示使用默认值(当前 PHP 进程的工作目录)。

env

要执行的命令所使用的环境变量。 设置此参数为 null 表示使用和当前 PHP 进程相同的环境变量。

other_options

你还可以指定一些附加选项。 目前支持的选项包括:

  • suppress_errors (仅用于 Windows 平台): 设置为 true 表示抑制本函数产生的错误。
  • bypass_shell (仅用于 Windows 平台): 设置为 true 表示绕过 cmd.exe shell。
  • blocking_pipes (仅用于 Windows 平台): 设置为 true 表示强制堵塞管道。
  • create_process_group (仅用于 Windows 平台): 设置为 true 表示允许子进程处理 CTRL 事件。
  • create_new_console (仅用于 Windows 平台): 表示新进程有一个新的控制台,用于代替父进程的控制台。

返回值

返回表示进程的资源类型, 当使用完毕之后,请调用 proc_close() 函数来关闭此资源。 如果失败,返回 false

更新日志

版本 说明
7.4.4 other_options 参数增加 create_new_console 选项。
7.4.0 proc_open()cmd 参数现在也允许数组类型。
7.4.0 other_options 参数增加 create_process_group 选项。

范例

示例 #1 proc_open() 例程

<?php
$descriptorspec 
= array(
   
=> array("pipe""r"),  // 标准输入,子进程从此管道中读取数据
   
=> array("pipe""w"),  // 标准输出,子进程向此管道中写入数据
   
=> array("file""/tmp/error-output.txt""a"// 标准错误,写入到一个文件
);

$cwd '/tmp';
$env = array('some_option' => 'aeiou');

$process proc_open('php'$descriptorspec$pipes$cwd$env);

if (
is_resource($process)) {
    
// $pipes 现在看起来是这样的:
    // 0 => 可以向子进程标准输入写入的句柄
    // 1 => 可以从子进程标准输出读取的句柄
    // 错误输出将被追加到文件 /tmp/error-output.txt

    
fwrite($pipes[0], '<?php print_r($_ENV); ?>');
    
fclose($pipes[0]);

    echo 
stream_get_contents($pipes[1]);
    
fclose($pipes[1]);
    

    
// 切记:在调用 proc_close 之前关闭所有的管道以避免死锁。
    
$return_value proc_close($process);

    echo 
"command returned $return_value\n";
}
?>

以上例程的输出类似于:

Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
command returned 0

示例 #2 proc_open() 在 Windows 上的怪异行为

虽然人们可能期望下面的程序能够搜索文件 filename.txt 进行文本搜索, 并打印结果,但它的行为相当不同。

<?php
$descriptorspec 
= [STDINSTDOUTSTDOUT];
$cmd '"findstr" "search" "filename.txt"';
$proc proc_open($cmd$descriptorspec$pipes);
proc_close($proc);
?>

以上例程会输出:

'findstr" "search" "filename.txt' is not recognized as an internal or external command,
operable program or batch file.

要解决该行为,通常只需将 cmd 加上引号:

$cmd = '""findstr" "search" "filename.txt""';

注释

注意:

Windows 兼容性:超过 2 的描述符也可以作为可继承的句柄传送到子进程。 但是,由于 Windows 的架构并不将文件描述符和底层句柄进行关联, 所以,子进程无法访问这样的句柄。 标准输入,标准输出和标注错误会按照预期工作。

注意:

如果你只需要单向的进程管道, 使用 popen() 函数会更加简单。

参见

  • popen() - 打开进程文件指针
  • exec() - 执行一个外部程序
  • system() - 执行外部程序,并且显示输出
  • passthru() - 执行外部程序并且显示原始输出
  • stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
  • The 执行运算符