<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.proc-open" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>proc_open</refname>

<refpurpose>

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

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>resource</type><type>false</type></type><methodname>proc_open</methodname>

<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>command</parameter></methodparam>

<methodparam><type>array</type><parameter>descriptor_spec</parameter></methodparam>

<methodparam><type>array</type><parameter role="reference">pipes</parameter></methodparam>

<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>cwd</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>env_vars</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>

</methodsynopsis>

<para>

Функция <function>proc_open</function> аналогична функции <function>popen</function>,

но предоставляет значительно больше контроля над выполнением программы.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>command</parameter></term>

<listitem>

<para>

Команда для выполнения, указанная как строка (&string;).

Специальные символы должны быть должным образом экранированы,

и должны применяться правильные кавычки.

</para>

<note>

<simpara>

В <emphasis>Windows</emphasis>, если для <literal>bypass_shell</literal> не установлено значение &true; в

<parameter>options</parameter>, <parameter>command</parameter>

передаётся в <command>cmd.exe</command> (точнее, <literal>%ComSpec%</literal>)

с флагом <literal>/c</literal> в виде строки <emphasis>без кавычек</emphasis>

(т.е. точно так, как было задано в <function>proc_open</function>).

Это может привести к тому, что <command>cmd.exe</command> удалит заключающие из

<parameter>command</parameter> (подробности смотрите в документации <command>cmd.exe</command>),

приводя к неожиданному и потенциально даже опасному поведению, потому что сообщения об ошибках <command>cmd.exe</command> могут содержать (частично) переданный параметр

<parameter>command</parameter> (смотрите пример ниже).

</simpara>

</note>

<para>

Начиная с PHP 7.4.0 параметр <parameter>command</parameter> разрешается передавать

как массив (&array;) параметров команды.

Тогда функция откроет процесс напрямую (не проходя через оболочку)

и PHP позаботится об экранировании любого необходимого аргумента.

</para>

<note>

<para>

В ОС Windows экранирование аргумента массива (&array;) элементов предполагает,

что синтаксический анализ выполненной команды совместим с синтаксическим анализом аргументов

командной строки, выполняемых средой выполнения VC.

</para>

</note>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>descriptor_spec</parameter></term>

<listitem>

<para>

Массив, ключи которого представляют собой номер дескриптора, а значение

описывает, как PHP должен передать этот дескриптор дочернему процессу.

0 — stdin, 1 — stdout и 2 — stderr.

</para>

<para>

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

<simplelist>

<member>

Массивом, описывающим канал (pipe) для передачи процессу. Первый

элемент — это дескриптор типа, второй - настройка для выбранного типа.

Возможные типы: <literal>pipe</literal> (второй элемент либо

<literal>r</literal> для передачи процессу стороны канала для

чтения, либо <literal>w</literal> для передачи стороны записи)

и <literal>file</literal> (второй элемент - имя файла).

Обратите внимание, что всё, кроме <literal>w</literal>, обрабатывается как <literal>r</literal>.

</member>

<member>

Ресурсом потока, представляющим дескриптор файла (например, открытый

файл, сокет, <constant>STDIN</constant>).

</member>

</simplelist>

</para>

<para>

Номера дескрипторов не ограничены только 0, 1 и 2 - вы можете назначить

любой действительный номер дескриптора и он будет передан дочернему

процессу. Это позволяет скрипту взаимодействовать с другими скриптами,

работающими, как параллельные процессы. В частности, таким образом можно

передавать данные, требующие защиты, в программы вроде PGP, GPG и

openssl более безопасно. Также это может оказаться полезным для чтения

статусной информации, предоставляемой этими программами на

вспомогательных файловых дескрипторах.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>pipes</parameter></term>

<listitem>

<para>

Будет задан массивом указателей на файлы, соответствующие созданным

каналам передачи данных PHP.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>cwd</parameter></term>

<listitem>

<para>

Рабочая директория команды. Это должен быть

<emphasis role="strong">абсолютный</emphasis> путь к директории или

&null;, если требуется использовать директорию по умолчанию (рабочая

директория текущего процесса PHP).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>env_vars</parameter></term>

<listitem>

<para>

Массив переменных окружения для запускаемой команды или &null;, если

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

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

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

поддерживаются следующие настройки:

<simplelist>

<member>

<literal>suppress_errors</literal> (только для Windows): при установке

в &true; не будут показываться ошибки, возникающие в ходе работы

функции

</member>

<member>

<literal>bypass_shell</literal> (только для Windows): при установке в

&true; процесс будет запущен в обход оболочки

<literal>cmd.exe</literal>

</member>

<member>

<literal>blocking_pipes</literal> (только для Windows): принудительно

блокировать поток при значении &true;

</member>

<member>

<literal>create_process_group</literal> (только для Windows): разрешить

дочернему процессу обрабатывать <literal>CTRL</literal> события, если установлено значение &true;

</member>

<member>

<literal>create_new_console</literal> (только для Windows): новый процесс использует новую консоль, а не наследует консоль своего родителя

</member>

</simplelist>

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Функция возвращает ресурс, который представляет процесс. Этот ресурс требуется освобождать

функцией <function>proc_close</function> по завершении работы с ним.

Функция возвращает &false;, если возникла ошибка.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

Начиная с версии PHP 8.3.0, функция выбрасывает ошибку <exceptionname>ValueError</exceptionname>,

если значение параметра <parameter>command</parameter> представляет собой массив,

в котором нет хотя бы одного непустого элемента.

</simpara>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.3.0</entry>

<entry>

Теперь функция выбрасывает ошибку <exceptionname>ValueError</exceptionname>,

если значение параметра <parameter>command</parameter> представляет собой массив,

в котором нет хотя бы одного непустого элемента.

</entry>

</row>

<row>

<entry>7.4.4</entry>

<entry>

Добавлена опция <literal>create_new_console</literal> в

параметр <parameter>options</parameter>.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

<function>proc_open</function> теперь также принимает массив (&array;)

в <parameter>command</parameter>.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Добавлена опция <literal>create_process_group</literal> в

параметр <parameter>options</parameter>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример использования <function>proc_open</function></title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

</para>

<para>

<example>

<title><function>proc_open</function> причуда в Windows</title>

<simpara>

Хотя можно ожидать, что следующая программа будет искать в файле

<filename>filename.txt</filename> текст <literal>search</literal>

и выводить результаты, она ведёт себя несколько иначе.

</simpara>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

<simpara>

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

</simpara>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

Совместимость с Windows: Дескрипторы дальше 2 (stderr) наследуются

дочерними процессам, однако с тех пор как Windows не ассоциирует номера

файловых дескрипторов с низкоуровневыми обработчиками, дочерние процессы

не имеют (пока) к ним доступа. Это не относится к stdin, stdout и stderr.

</para>

</note>

<note>

<para>

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

<function>popen</function>, так как она значительно проще в использовании.

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>popen</function></member>

<member><function>exec</function></member>

<member><function>system</function></member>

<member><function>passthru</function></member>

<member><function>stream_select</function></member>

<member><link linkend="language.operators.execution">Оператор обратный апостроф</link></member>

</simplelist>

</para>

</refsect1>

</refentry>