(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
proc_open — Ejecuta un comando y abre los punteros de ficheros para las entradas / salidas
$command,$descriptor_spec,&$pipes,$cwd = null,$env_vars = null,$options = nullproc_open() es similar a popen() pero proporciona un mayor grado de control sobre la ejecución del programa.
commandEl comando a ejecutar como string. Los caracteres especiales deben ser escapados correctamente, y una aplicación correcta de las comillas debe ser aplicada.
Nota: En Windows, a menos que
bypass_shellesté definida atrueenoptions,commandes pasado a cmd.exe (en realidad,%ComSpec%) con el flag/ccomo un string sin comillas (es decir, exactamente como fue proporcionado a proc_open()). Esto puede causar cmd.exe para eliminar las comillas que rodeancommand(para más detalles ver la documentación de cmd.exe), resultando en un comportamiento inesperado, y potencialmente peligroso, ya que los mensajes de error de cmd.exe pueden contener (una parte de) lacommandpasada (ver ejemplo a continuación).
A partir de PHP 7.4.0, command puede ser pasado como
un array de argumentos de comandos.
En este caso el proceso será abierto directamente (sin pasar por un shell) y PHP se encargará de escapar los argumentos necesarios.
Nota:
En Windows, el escape de los argumentos de los elementos del array asume que el procesamiento de la línea de comandos del comando ejecutado es compatible con el procesamiento de argumentos de línea de comandos realizado por el runtime VC.
descriptor_specUn array indexado, donde las claves representan el número de descriptor y el valor el método con el cual PHP pasará este descriptor al proceso hijo. 0 es stdin, 1 es stdout, y 2 es stderr.
Cada elemento puede ser:
pipe (el segundo elemento es
r para pasar el extremo de lectura del pipe al proceso, o
w para pasar el extremo de escritura) y
file (el segundo elemento es el nombre de fichero).
Se debe notar que cualquier otro elemento diferente de w es tratado como r.
STDIN).
Los números de punteros de ficheros no están limitados a 0, 1 y 2 - se puede especificar cualquier número de descriptor válido, y será pasado al proceso hijo. Esto permitirá que su script interactúe con otros scripts, y que sea ejecutado como "co-proceso". En particular, es muy práctico para pasar contraseñas a programas como PGP, GPG y openssl, con un método muy protegido. También es práctico para leer información de estado proporcionada por estos programas, en descriptores auxiliares.
pipesDebe ser definido como un array indexado de punteros de ficheros que corresponden al extremo de cualquier descriptor PHP que sean creados.
cwd
El directorio inicial de trabajo del comando. Esto debe ser
una ruta absoluta
al directorio o null si se quiere utilizar el valor
por omisión (el directorio de trabajo del proceso PHP actual)
env_vars
Un array que contiene las variables de entorno para el comando
que debe ser ejecutado, o null para utilizar el mismo entorno
que el proceso PHP actual
optionsPermite especificar opciones adicionales. Las opciones actualmente soportadas son:
suppress_errors (solo Windows): supresión de
errores generados por esta función cuando está definida a true
bypass_shell (solo Windows): omisión del shell
cmd.exe cuando está definida a true
blocking_pipes (solo Windows): fuerza
los pipes bloqueantes cuando está definida a true
create_process_group (solo Windows): permite
al proceso hijo manejar los eventos CTRL
cuando está a true
create_new_console (solo Windows): el nuevo
proceso tiene una nueva consola, en lugar de heredar la consola de su
padre.
Retorna un recurso que representa el proceso, que podrá ser utilizado por
la función proc_close() cuando ya no sea necesario.
En caso de fallo, false será retornado.
A partir de PHP 8.3.0, se lanza una excepción ValueError si
command es un array sin al menos un elemento no vacío.
| Versión | Descripción |
|---|---|
| 8.3.0 |
Se lanzará una excepción ValueError si
command es un array sin al menos un elemento no vacío.
|
| 7.4.4 |
Se añadió la opción create_new_console al parámetro
options.
|
| 7.4.0 |
proc_open() ahora acepta un array
para command.
|
| 7.4.0 |
Se añadió la opción create_process_group al parámetro
options.
|
Ejemplo #1 Ejemplo con proc_open()
<?php
$descriptorspec = array(
0 => array("pipe", "r"), // stdin es un pipe donde el proceso leerá
1 => array("pipe", "w"), // stdout es un pipe donde el proceso escribirá
2 => array("file", "/tmp/error-output.txt", "a") // stderr es un fichero
);
$cwd = '/tmp';
$env = array('some_option' => 'aeiou');
$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);
if (is_resource($process)) {
// $pipes se parece a:
// 0 => fichero accesible en escritura, conectado a la entrada estándar del proceso hijo
// 1 => fichero accesible en lectura, conectado a la salida estándar del proceso hijo
// Cualquier error será añadido al fichero /tmp/error-output.txt
fwrite($pipes[0], '<?php print_r($_ENV); ?>');
fclose($pipes[0]);
echo stream_get_contents($pipes[1]);
fclose($pipes[1]);
// Es importante que cierre los pipes antes de llamar
// a proc_close para evitar un bloqueo.
$return_value = proc_close($process);
echo "El comando retornó $return_value\n";
}
?>Resultado del ejemplo anterior es similar a :
Array
(
[some_option] => aeiou
[PWD] => /tmp
[SHLVL] => 1
[_] => /usr/local/bin/php
)
El comando retornó 0
Ejemplo #2 Comportamiento extraño de proc_open() en Windows
Aunque se podría esperar que el siguiente programa busque
el fichero filename.txt para el texto
search y muestre los resultados,
se comporta de manera diferente.
<?php
$descriptorspec = [STDIN, STDOUT, STDOUT];
$cmd = '"findstr" "search" "filename.txt"';
$proc = proc_open($cmd, $descriptorspec, $pipes);
proc_close($proc);
?>El ejemplo anterior mostrará :
'findstr" "search" "filename.txt' no se reconoce como un comando interno o externo, programa ejecutable o archivo por lotes.
Para evitar este comportamiento, generalmente es suficiente rodear
command con comillas adicionales:
$cmd = '""findstr" "search" "filename.txt""';Nota:
Compatibilidad Windows: los descriptores más allá de 2 (stderr) son accesibles al proceso hijo, en forma de punteros heredados, pero como la arquitectura Windows no asocia números a los descriptores de bajo nivel, el proceso hijo no tiene, actualmente, ningún medio para acceder a ellos. Por otro lado, stdin, stdout y stderr funcionan como de costumbre.
Nota:
Si solo se necesita un proceso unidireccional, popen() será más práctico, ya que es más sencillo de utilizar.