proc_open

(PHP 4 >= 4.3.0, PHP 5)

proc_open — Ejecutar un comando y abrir apuntadores de archivo para entrada/salida

Descripción

resource proc_open ( string $cmd , array $espec_descriptor , array &$pipes [, string $cwd [, array $env [, array $otras_opciones ]]] )

proc_open() es similar a popen() pero provee un grado de control mucho mayor sobre la ejecución del programa.

Lista de parámetros

cmd

El comando a ejecutar

espec_descriptor

Una matriz indexada en donde las llaves representan el número del descriptor y el valor representa el modo en que PHP pasará el descriptor al proceso hijo. 0 es stdin, 1 es stdout, y 2 es stderr.

Los tipos de pipe soportados actualmente son file y pipe .

Los números de descriptor de archivo no se limitan a 0, 1 y 2 - es posible que especifique cualquier número de descriptor de archivo válido y éste será pasado al proceso hijo. Esto le permite a su script interoperar con otros scripts que corren como "co-procesos". En particular, esto es útil para pasar frases secretas a programas como PGP, GPG y openssl de una forma más segura. También es útil para leer información de status ofrecida por esos programas en descriptores de archivo auxiliares.

pipes

Recibirá como valor una matriz indexada de apuntadores de archivo que corresponden a los valores en PHP de los pipes creados.

cwd

El directorio de trabajo inicial para el comando. Este debe ser una ruta de directorio absoluta, o NULL si desea usar el valor predeterminado (el directorio de trabajo del proceso PHP actual)

env

Una matriz con las variables de entorno para el comando que será ejecutado, o NULL para usar el mismo entorno que el proceso PHP actual

otras_opciones

Le permite especificar opciones adicionales. Las opciones actualmente soportadas incluyen:

suppress_errors (sólo en windows): elimina errores generados por esta función cuando se define como TRUE
bypass_shell (sólo en windows): evita el intérprete de comandos cmd.exe cuando se define como TRUE
context: contexto de secuencia usado cuando se abren archivos (creado con stream_context_create())
binary_pipes: abrir pipes en modo binario, en lugar de usar el valor stream_encoding usual

Valores retornados

Devuelve un recurso que representa el proceso, el cual debe ser liberado usando proc_close() cuando haya terminado de usarlo. En caso de error, devuelve FALSE.

Registro de cambios

Versión Descripción

6.0.0 Se agregaron las opciones context y binary_pipes al parámetro otras_opciones .

5.2.1 Se agregó la opción bypass_shell al parámetro otras_opciones .

5.0.0 Se añadieron los parámetros cwd , env y otras_opciones .

Ejemplos

Example #1 Un ejemplo de proc_open()

<?php
$espec_descriptor = array(
   0 => array("pipe", "r"),  // stdin es un pipe usado por el hijo para lectura
   1 => array("pipe", "w"),  // stdout es un pipe usado por el hijo para escritura
   2 => array("file", "/tmp/salida-errores.txt", "a") // stderr es un archivo para escritura
);

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

$proceso = proc_open('php', $espec_descriptor, $pipes, $cwd, $env);

if (is_resource($proceso)) {
    // $pipes ahora luce de esta forma:
    // 0 => gestor de escritura conectado con la entrada estándar del hijo
    // 1 => gestor de lectura conectado con la salida estándar del hijo
    // Cualquier mensaje de salida de error será adicionado a /tmp/salida-errores.txt

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

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

    // Es importante que cierre todos los pipes antes de llamar
    // proc_close para evitar un bloqueo muerto
    $retval = proc_close($proceso);

    echo "el comando ha devuelto $retval\n";
}
?>

El resultado del ejemplo seria algo similar a:

Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
el comando ha devuelto 0

Notes

Note: Compatibilidad con Windows: Los descriptores más allá de 2 (stderr) se ponen a disposición del proceso hijo como gestores heredables, pero ya que la arquitectura de Windows no asocia números de descriptores de archivo con gestores de bajo nivel, el proceso hijo no tiene (aun) una forma de acceder a esos gestores. Stdin, stdout y stderr funcionan como es de esperarse.

Note: Si solo necesita un pipe de proceso uni-direccional (de una vía), use popen() en su lugar, ya que es mucho más fácil de usar.