proc_open

(PHP 4 >= 4.3.0, PHP 5)

proc_open — Ejecuta un comando y abre un puntero de fichero para entrada/salida

Descripción

resource proc_open ( string $cmd , array $descriptorspec , array &$pipes [, string $cwd [, array $env [, array $other_options ]]] )

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

Parámetros

cmd

El comando a ejecutar

descriptorspec

Un array indexado donde la clave representa el número descriptor y el valor representa como PHP pasará que descriptor para que proceso hijo. 0 es stdin, 1 es stdout, 2 es stderr.

Cada elemento puede ser:

  • Un array que describe la tubería que se va a pasar al proceso. El primer elemento es el tipo de descriptor, y el segundo elemento es una opción para el tipo dado. Los tipos válidos son: pipe (en este caso el segundo elemento sería r para pasar a leer el final de la tubería para el proceso, o w para pasar a escribir al final) y file (en este caso el segundo elemento sería el nombre de fichero).
  • Un recurso de flujo representando un descriptor de un fichero real (p.e. un fichero abierto, un socket, STDIN).

Los números descriptores de fichero no estan limitados a 0, 1 y 2. Se puede especificar cualquier número descriptor válido de fichero, y este ser pasado al proceso hijo. Esto permite a su script para inteoperar con otros scripts que corren como "co-procesos". En particular esto es útil pasando passphrases para programas como PGP, GPG y OpenSSL de una manera más segura. Esto es útil también para la lectura de la información del estado provista por estos programas en descriptores de fichero auxiliares.

pipes

En un array indexado es establecerán los punteros de fichero que se corresponden con el fin de cualquier tuberia PHP que se haya creado.

cwd

El directorio inicial de trabajo para el comando. Este debe ser una ruta absoluta, o si se prefiere puede ser NULL si se desea usar el valor por defecto (entonces será el directorio de trabajo del proceso PHP en curso)

env

Un array con las variables de entorno para el comando que será ejecutado, o NULL para usar el mismo entorno como el del proceso PHP en curso.

other_options

Permite especificar opciones adicionales. Actualmente las opciones soportadas incluidas son:

  • suppress_errors (solo windows): suprime errores generados por esta función cuando es establece en TRUE
  • bypass_shell (solo windows): Desvia en la consola de cmd.exe cuando se establece en TRUE

Valores devueltos

Devuelve un recurso representando el proceso, cuando se haya terminado con él, deberá ser liberado usandoproc_close(). En caso de error devuelve FALSE.

Historial de cambios

Versión Descripción
5.2.1 Añadida la opción bypass_shell al parámetro other_options.

Ejemplos

Ejemplo #1 Ejemplo de proc_open()

<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // stdin es una tubería usada por el hijo para lectura
   1 => array("pipe", "w"),  // stdout es una tubería usada por el hijo para escritura
   2 => array("file", "/tmp/error-output.txt", "a") // stderr es un fichero para escritura
);

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

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

if (is_resource($process)) {
    // $pipes ahora será algo como:
    // 0 => gestor de escritura conectado al stdin hijo
    // 1 => gestor de lectura conectado al stdout hijo
    // Cualquier error de salida será anexado a /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 se cierren todas las tubería antes de llamar a
    // proc_close para evitar así un punto muerto
    $return_value = proc_close($process);

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

El resultado del ejemplo sería algo similar a:

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

Notas

Nota:

Compatibilidad con Windows: Los descriptores por encima de 2 (stderr) se ponen a disposición del proceso hijo como gestores heredables, pero desde la arquitectura de Windows no se asocia el número descriptor de fichero con los gestores de bajo nivel. El proceso hijo (todavia) no tiene un medio de acceso a estos gestores. Stdin, stdout and stderr funcionan como se esperaba.

Nota:

Si solamente se necesita una tubería de proceso unidireccional, es mejor usar popen() en su lugar, ya que es mucho más fácil de utilizar.

Ver también

  • popen() - Abre un proceso de un puntero a un fichero
  • exec() - Ejecutar un programa externo
  • system() - Ejecutar un programa externo y mostrar su salida
  • passthru() - Ejecuta un programa externo y muestra la salida en bruto
  • stream_select() - Ejecuta el equivalente de la llamada al sistema select() sobre las matrices de flujos dadas con un tiempo de espera especificado por tv_sec y tv_usec
  • The backtick operator