Cap�tulo 25. Usando o PHP na linha de comando

Desde a vers�o 4.3, o PHP suporta um novo tipo SAPI (Server Application Programming Interface) chamado CLI que significa Command Line Interface. Como o pr�prio nome diz, essa SAPI tem foco no desenvolvimento de aplica��es shell (ou no terminal/linha de comando) com o PHP. As diferen�as entre a CLI SAPI e as outras SAPIs s�o detalhadas neste cap�tulo.

A CLI SAPI foi liberada primeiramente com o PHP 4.2.0, mas ainda em est�gio experimental, sendo necess�rio ativ�-la explicitamente com a op��o --enable-cli durante o ./configure. Desde o PHP 4.0.3 a CLI SAPI n�o mais � experimental e � sempre compilada e instalada como o arquivo php (chamado php.exe no Windows), no formato bin�rio execut�vel.

Diferen�as importantes das CLI SAPI comparada com outras SAPIs:

• Diferentemente da CGI SAPI, nenhum header � impresso na sa�da.

  A CGI SAPI possui um meio de suprimir os headers HTTP, mas n�o h� uma chave equivalente para ativ�-los na CLI SAPI.

• Estas s�o as diretivas do php.ini que s�o sobrescritas pela CLI SAPI porque n�o fazem sentido no ambiente shell:

  Tabela 25-1. Diretivas php.ini sobrescritas

  Diretiva	Valor default CLI SAPI	Coment�rios
  html_errors	FALSE	Pode ser bem dif�cil de ler mensagens de erro no seu shell quando elas est�o embebidas dentro de tags HTML, por isso essa diretiva tem default para FALSE.
  implicit_flush	TRUE	Essa diretiva causa que qualquer sa�da gerada de um print(), echo() e semelhantes sejam imediatamente escritas para o output e n�o cacheadas em nenhum buffer. Voc� ainda pode usar o output buffering se voc� precisa atrasar ou manipular a sa�da padr�o.
  max_execution_time	0 (unlimited)	Devido as infinitas possibilidades da utiliza��o do PHP em ambientes shell, tempo m�ximo de execu��o foi configurado para ilimitado. Enquanto aplica��es escritas para web s�o geralmente executadas em poucos segundos, aplica��es no shell tendem a ter um tempo de execu��o mais longo.
  register_argc_argv	TRUE	As vari�veis globais do PHP $argc (n�mero de argumentos passados para aplica��o) e $argv (array com os argumentos atuais) s�o sempre presentes e preenchidos com os valores apropriados quando utilizando a CLI SAPI.

  Nota: Estas diretivas n�o podem ser inicializadas com outros valores do arquivo de configura��o php.ini ou um arquivo personalizado (se informado). Esta limita��o existe porque estes valores s�o aplicados depois que todos os arquivos de configura��o s�o analisados. Entretanto, seus valores podem ser modificados durante a execu��o (o que pode n�o fazer sentido para todas elas, por exemplo, register_argc_argv).

• Para facilicar a opera��o no ambiente shell, as seguintes constantes est�o definidas:

  Tabela 25-2. Constantes espec�ficas CLI

  Constante	Descri��o
  STDIN	Um stream j� aberto para o stdin. Isto economiza ter de abr�-lo com $stdin = fopen('php://stdin', 'r');
  STDOUT	Um stream j� aberto para o stdout. Isto economiza ter de abr�-lo com $stdout = fopen('php://stdout', 'w');
  STDERR	Um stream j� aberto para o stderr. Isto economiza ter de abr�-lo com $stderr = fopen('php://stderr', 'w');

  Considerando isso, voc� n�o precisar� mais abr�-los, por exemplo o stderr voc� mesmo, mas simplesmente usar a constante em vez do recurso stream:

  php -r 'fwrite(STDERR, "stderr\n");'

  Voc� n�o precissa fechar explicitamente esses streams. Isto � realizado automaticamente pelo PHP.

• A CLI SAPI n�o modifica o diret�rio de execu��o atual para o diret�rio onde o script � interpretado!

  Exemplo mostrando a diferen�a da CGI SAPI:

  <?php /* Nossa aplica��o de teste */ echo getcwd(), "\n"; ?>

  Quando utilizando a vers�o CGI, a sa�da �

  $ pwd /tmp $ php-cgi -f outro_diretorio/test.php /tmp/outro_diretorio

  Isto mostra como o PHP modifica o diret�rio atual para aquela onde o script � executado.

  Utilizando a vers�o CLI SAPI:

  $ pwd /tmp $ php -f outro_diretorio/test.php /tmp

  E isto mostra a grande flexibilidade ferramentas shell em PHP.

  Nota: A CGI SAPI suporta o comportamento da CLI SAPI utilizando a chave -C quando de sua execu��o na linha de comando.

A lista de op��es de linha de comando fornecidas pelo bin�rio do PHP pode ser solicitada a qualquer tempo executando o PHP com a op��o -h:

Usage: php [options] [-f] <file> [args...]
       php [options] -r <code> [args...]
       php [options] [-- args...]
  -s               Display colour syntax highlighted source.
  -w               Display source with stripped comments and whitespace.
  -f <file>        Parse <file>.
  -v               Version number
  -c <path>|<file> Look for php.ini file in this directory
  -a               Run interactively
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -z <file>        Load Zend extension <file>.
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -i               PHP information
  -r <code>        Run PHP <code> without using script tags <?..?>
  -h               This help

  args...          Arguments passed to script. Use -- args when first argument
                   starts with - or script is read from stdin

A CLI SAPI fornecer tr�s maneiras diferentes para voc� executar seu c�digo PHP:

1. Chamando o PHP para executar um arquivo determinado.

   php my_script.php php -f my_script.php

   De ambas maneiras (utilizando ou n�o a op��o -f) o arquivo informado my_script.php � executado. Voc� pode escolher qualquer arquivo para executar, seus scripts PHP n�o precisam terminar com a extens�o .php, podendo ter qualquer nome ou extens�o que voc� deseje.

2. Passar o c�digo PHP para execu��o diretamente a linha de comando.

   php -r 'print_r(get_defined_constants());'

   � preciso ter especial cuidado com a substitui��o de vari�veis shell e delimita��o de strings utilizada.

   Nota: Leia o exemplo cuidadosamente, observando que n�o h� tags de abertura ou fechamento! A op��o -r simplesmente n�o precisa delas. Utilizando-as voc� obter� erros de interpreta��o.

3. Fornece c�digo PHP para interpreta��o via a entrada padr�o (stdin).

   Isto mostra a habilidade poderosa de como criar dinamicamente c�digo PHP e fornec�-lo ao bin�rio, como demonstrado neste exemplo (apenas demonstrativo):

   $ alguma_aplicacao | algum_filtro | php | sort -u >final_output.txt

Assim como qualquer aplica��o shell, n�o somente o bin�rio do PHP aceita um certo n�mero de argumentos, mas tamb�m seu script PHP tamb�m pode receb�-los. O n�mero de argumentos que podem ser passados para seu script n�o � limitado ao PHP (mas o shell tem um certo limite de tamanho em caracteres que podem ser informados, e n�o h� um padr�o para esse limite). Os argumentos passados para seu script s�o disponibilizados no array global $argv. No �ndice zero sempre conter� o nome do script (podendo ser - no caso de c�digo PHP estar vindo da entrada padr�o ou da op��o de linha de comando -r). O segunda vari�vel global $argc cont�m o n�mero de elementos no array $argv (mas n�o o n�mero de argumentos passados para seu script.

Os argumentos que voc� deseja passar para seu script n�o podem come�ar com o caracter - e isso n�o pode ser modificado. Passando argumentos para seu script que comecem com um - causar� problemas porque o PHP tentar� manuse�-los. Para prevenir isso, utilize o separador de argumentos --. Depois que os argumentos s�o interpretados pelo PHP, todos os argumentos restantes s�o repassados intocados para seu script.

# Isto n�o executar� o c�digo fornecido e ir� fazer o PHP mostrar sua ajuda
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# Isto passar� o argumento '-h' para seu script e prevenir� o PHP de us�-lo
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Entretanto, h� ainda uma outra maneira de se utilizar o PHP no shell. Voc� pode escrever um script que na primeira linha tenha #!/usr/bin/php e na seq��ncia tenha c�digo PHP normal, incluindo as tags de in�cio e fim e os atributos de execu��o do arquivo. Desta maneira ele pode ser executado como um script shell ou PERL normalmente:

#!/usr/bin/php
<?php
    var_dump($argv);
?>

$ chmod 755 teste
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./teste"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

$ php -v
PHP 4.3.0-dev (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.2.1, Copyright (c) 1998-2002 Zend Technologies

$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

-d diretiva[=valor]

# Omitindo a parte do valor ir� configurar a diretiva para "1"
$ php -d max_execution_time -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Passando um valor vazio ir� configurar a diretiva para ""
php -d max_execution_time= -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# A diretiva de configura��o ser� preenchida com qualquer coisa informada depois do caracter =''
$  php -d max_execution_time=20 -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php -d max_execution_time=instonaofazsentido -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "instonaofazsentido"

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

O PHP execut�vel pode ser utilizando para rodar scripts PHP absolutamente independente de um servidor web. Se voc� est� num sistema Unix, voc� pode acrescentar uma linha especial na primeira linha de seu script e torn�-lo execut�vel, ent�o o sistema operacional saber� que programa dever� rodar o script. Na plataforma Windows, voc� pode associar php.exe -q com o clique duplo em arquivos .php ou fazer um arquivo batch para rodar seus scripts atrav�s do PHP. A primeira linha acrescentada ao script nos Unix n�o funcionam no Windows, por isso voc� n�o pode escrever programas independentes de plataforma desse jeito. Um exemplo simples de como escrever um programa para a linha de comando segue abaixo:

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

Este � um script de linha de comando com um par�metro.

  Uso:
  <?php echo $argv[0]; ?> <opcao>

  <opcao> pode ser qualquer palavra que
  voc� queira imprimir. Com as op��es --help, -help, -h
  ou -?, voc� pode obter essa ajuda.

<?php
} else {
    echo $argv[1];
}
?>

No script acima, n�s utilizamos uma primeira linha especial para indicar que este arquivo precisa rodar pelo PHP. Como n�s trabalhamos com a vers�o CLI aqui, n�o ser�o impressos headers HTTP. H� duas vari�veis que voc� precisa conhecer para escrever aplica��es em linha de comando com o PHP: $argc e $argv. O primeiro � o n�mero de argumentos mais um (o nome do script executando). O segundo � um array contendo os argumentos, come�ando com o nome do script no �ndice zero ($argv[0]).

No programa acima � verificado se h� apenas um argumento fornecido. Se o argumento for --help, -help, -h ou -?, � impresso uma mensagem de ajuda, imprimindo o nome do script dinamicamente. Qualquer outro argumento � exibido como informado.

Para rodar esse aplicativo nos Unix, basta torn�-lo execut�vel e o chamar diretamente como script.php exibaisso ou script.php -h. No Windows, voc� pode fazer um arquivo batch para esta tarefa:

@c:\php\php.exe script.php %1 %2 %3 %4

Assumindo que voc� nomeou o programa acima como script.php, e voc� tem um php.exe em c:\php\php.exe este arquivo batch ir� rodar com os seguintes par�metros: script.bat exibaisso ou script.bat -h.

Veja tamb�m a documenta��o da extens�o Readline para mais fun��es que voc� pode usar para incrementar suas aplica��es para linha de comando em PHP.