array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'ru', ), 'this' => array ( 0 => 'function.proc-open.php', 1 => 'proc_open', 2 => 'Выполняет команду и открывает указатель на файл для ввода или вывода', ), 'up' => array ( 0 => 'ref.exec.php', 1 => 'Функции запуска программ', ), 'prev' => array ( 0 => 'function.proc-nice.php', 1 => 'proc_nice', ), 'next' => array ( 0 => 'function.proc-terminate.php', 1 => 'proc_terminate', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'ru', 'path' => 'reference/exec/functions/proc-open.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

proc_open

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

proc_open — Выполняет команду и открывает указатель на файл для ввода или вывода

Описание

proc_open(
    array|string $command,
    array $descriptor_spec,
    array &$pipes,
    ?string $cwd = null,
    ?array $env_vars = null,
    ?array $options = null
): resource|false

Функция proc_open() аналогична функции popen(), но предоставляет значительно больше контроля над выполнением программы.

Список параметров

command

Команда для выполнения, указанная как строка (string). Специальные символы должны быть должным образом экранированы, и должны применяться правильные кавычки.

Замечание: В Windows, если для bypass_shell не установлено значение true в options, command передаётся в cmd.exe (точнее, %ComSpec%) с флагом /c в виде строки без кавычек (т.е. точно так, как было задано в proc_open()). Это может привести к тому, что cmd.exe удалит заключающие из command (подробности смотрите в документации cmd.exe), приводя к неожиданному и потенциально даже опасному поведению, потому что сообщения об ошибках cmd.exe могут содержать (частично) переданный параметр command (смотрите пример ниже).

Начиная с PHP 7.4.0 параметр command разрешается передавать как массив (array) параметров команды. Тогда функция откроет процесс напрямую (не проходя через оболочку) и PHP позаботится об экранировании любого необходимого аргумента.

Замечание:

В ОС Windows экранирование аргумента массива (array) элементов предполагает, что синтаксический анализ выполненной команды совместим с синтаксическим анализом аргументов командной строки, выполняемых средой выполнения VC.

descriptor_spec

Массив, ключи которого представляют собой номер дескриптора, а значение описывает, как PHP должен передать этот дескриптор дочернему процессу. 0 — stdin, 1 — stdout и 2 — stderr.

Каждый элемент может быть:

  • Массивом, описывающим канал (pipe) для передачи процессу. Первый элемент — это дескриптор типа, второй - настройка для выбранного типа. Возможные типы: pipe (второй элемент либо r для передачи процессу стороны канала для чтения, либо w для передачи стороны записи) и file (второй элемент - имя файла). Обратите внимание, что всё, кроме w, обрабатывается как r.
  • Ресурсом потока, представляющим дескриптор файла (например, открытый файл, сокет, STDIN).

Номера дескрипторов не ограничены только 0, 1 и 2 - вы можете назначить любой действительный номер дескриптора и он будет передан дочернему процессу. Это позволяет скрипту взаимодействовать с другими скриптами, работающими, как параллельные процессы. В частности, таким образом можно передавать данные, требующие защиты, в программы вроде PGP, GPG и openssl более безопасно. Также это может оказаться полезным для чтения статусной информации, предоставляемой этими программами на вспомогательных файловых дескрипторах.

pipes

Будет задан массивом указателей на файлы, соответствующие созданным каналам передачи данных PHP.

cwd

Рабочая директория команды. Это должен быть абсолютный путь к директории или null, если требуется использовать директорию по умолчанию (рабочая директория текущего процесса PHP).

env_vars

Массив переменных окружения для запускаемой команды или null, если требуется использовать то же самое окружение, что и у текущего PHP-процесса.

options

Позволяет задать дополнительные настройки. На данный момент поддерживаются следующие настройки:

  • suppress_errors (только для Windows): при установке в true не будут показываться ошибки, возникающие в ходе работы функции
  • bypass_shell (только для Windows): при установке в true процесс будет запущен в обход оболочки cmd.exe
  • blocking_pipes (только для Windows): принудительно блокировать поток при значении true
  • create_process_group (только для Windows): разрешить дочернему процессу обрабатывать CTRL события, если установлено значение true
  • create_new_console (только для Windows): новый процесс использует новую консоль, а не наследует консоль своего родителя

Возвращаемые значения

Функция возвращает ресурс, который представляет процесс. Этот ресурс требуется освобождать функцией proc_close() по завершении работы с ним. Функция возвращает false, если возникла ошибка.

Ошибки

Начиная с версии PHP 8.3.0, функция выбрасывает ошибку ValueError, если значение параметра command представляет собой массив, в котором нет хотя бы одного непустого элемента.

Список изменений

Версия Описание
8.3.0 Теперь функция выбрасывает ошибку ValueError, если значение параметра command представляет собой массив, в котором нет хотя бы одного непустого элемента.
7.4.4 Добавлена опция create_new_console в параметр options.
7.4.0 proc_open() теперь также принимает массив (array) в command.
7.4.0 Добавлена опция create_process_group в параметр options.

Примеры

Пример #1 Пример использования proc_open()

<?php
$descriptorspec = array(
0 => array("pipe", "r"), // stdin - канал, из которого дочерний процесс будет читать
1 => array("pipe", "w"), // stdout - канал, в который дочерний процесс будет записывать
2 => array("file", "/tmp/error-output.txt", "a") // stderr - файл для записи
);

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

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

if (is_resource($process)) {
// $pipes теперь выглядит так:
// 0 => записывающий обработчик, подключённый к дочернему stdin
// 1 => читающий обработчик, подключённый к дочернему stdout
// Вывод сообщений об ошибках будет добавляться в /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 "команда вернула $return_value\n";
}
?>

Вывод приведённого примера будет похож на: 

Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
команда вернула 0

Пример #2 proc_open() причуда в Windows

Хотя можно ожидать, что следующая программа будет искать в файле filename.txt текст search и выводить результаты, она ведёт себя несколько иначе.

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

Результат выполнения приведённого примера: 

'findstr" "search" "filename.txt' не распознается как внутренняя или внешняя команда,
работающая программа или пакетный файл.

Чтобы обойти это поведение, обычно достаточно передать command в дополнительных кавычках:

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

Примечания

Замечание:

Совместимость с Windows: Дескрипторы дальше 2 (stderr) наследуются дочерними процессам, однако с тех пор как Windows не ассоциирует номера файловых дескрипторов с низкоуровневыми обработчиками, дочерние процессы не имеют (пока) к ним доступа. Это не относится к stdin, stdout и stderr.

Замечание:

Если нужен однонаправленный канал процесса, используйте функцию popen(), так как она значительно проще в использовании.

Смотрите также