proc_open

(PHP 4 >= 4.3.0, PHP 5)

proc_open — Executa um comando e abre ponteiros para entrada e saída

Descrição

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

proc_open() é similar a popen() mas provê uma grau de controle muito maior sobre a execução do programa.

Parâmetros

cmd

O comando a executar

descriptorspec

Uma matriz indexada aonde a chave representa o número do descritor e o valor representa como o PHP passará este descritor para o processo filho. 0 é stdin, 1 é stdout, enquanto 2 é stderr.

Os pipes suportados atualmente são file e pipe .

Os números dos descritores de arquivos não estão limitados a 0, 1 e 2 - você pode especificar qualquer número de descritor válido e ele será passado para o processo filho. Isto permiteao seu script interoperar com outros scripts que sejam executados como "co-processos". Em particular, isto é útil para passar senhas para programas como PGP, GPG e openssl de uma maneira mais segura. Também é útil para ler informações do estado providos por esses programas em descritores auxiliares.

pipes

Sera definido como uma matriz indexada de ponteiros de arquivos que corresponde aos pipes do lado do PHP que são criados.

cwd

O diretório inicial de trabalho para o comando. Este deve ser um caminho absoluto, ou NULL se você quer usar o valor padrão (o diretório de trabalho do processo PHP atual)

env

Uma matriz de variáveis de ambiênte para o comando que será executado, ou NULL para usar o mesmo ambiênte que o processo PHP atual.

other_options

Permite a você definir opções adicionais. Opções atualmente suportadas incluem:

  • suppress_errors (apenas windows): suprime os erros gerados por esta função quando estiver definido como TRUE
  • bypass_shell (apenas windows): ignora o shell cmd.exe quando esta definido como TRUE
  • context: contexto de stream usado ao abrir arquivos (criado com stream_context_create())
  • binary_pipes: abre os pipes em modo binário, ao invés de usar o stream_encoding

Valor Retornado

Retorna um recurso representando o processo, o qual deve ser liberado usando proc_close() quando você terminou de utiliza-lo. Em caso de falha retorna FALSE.

Changelog

Versão Descrição
6.0.0 Adicionado as opções context e binary_pipes no parâmetro other_options.
5.2.1 Adicionada a opção bypass_shell ao parâmetro other_options.
5.0.0 Adicionado os parâmetros cwd, env e other_options.

Exemplos

Example #1 Um exemplo proc_open()

<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // stdin is a pipe that the child will read from
   1 => array("pipe", "w"),  // stdout is a pipe that the child will write to
   2 => array("file", "/tmp/error-output.txt", "a") // stderr is a file to write to
);

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

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

if (is_resource($process)) {
    // $pipes now looks like this:
    // 0 => writeable handle connected to child stdin
    // 1 => readable handle connected to child stdout
    // Any error output will be appended to /tmp/error-output.txt

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

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

    // It is important that you close any pipes before calling
    // proc_close in order to avoid a deadlock
    $return_value = proc_close($process);

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

O exemplo acima irá imprimir algo similar à:

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

Notas

Note:

Compatibilidade com Windows: Descritores além do 2(stderr) são tornados disponíveis ao processo filho como manipuladores herdados, mas já que a arquitetura Windows não associa números de descritores de arquivos com os manipuladores de baixo nível, o processo filho (ainda) não tem meios de acessar estes manipuladores. Stdin, stdout e stderr funcionam como esperado.

Note:

Se você precisa de um pipe de processo de apenas uma direção, use popen() ao invés, já que é muito mais fácil de usar.

Veja Também

  • popen() - Abre um processo como ponteiro de arquivo
  • exec() - Executa um programa externo
  • system() - Executa um programa externo e mostra a saída
  • passthru() - Executa um programa externo e mostra a saída crúa
  • stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
  • O operador backtick