Capítulo 24. 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:

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

Você não pode combinar nenhum das três maneiras para executar código.

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);
?>
Assumindo que o arquivo foi nomeado como teste e está no diretório atual, nós podemos fazer o seguinte:
$ chmod 755 teste
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./teste"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}
Como você viu, dessa forma não há problemas em passar parâmetros para seu script que comecem com o caracter -

Tabela 24-3. Opções de linha de comando

OpçãoDescrição
-s

Mostra o código fonte com destaque de cores.

Esta opção usa o mecanismo interno para interpretar o arquivo e produzir uma versão HTML do fonte com destaque de cores e a envia para a saída padrão. Note que ele somente gerará blocos de <code> [...] </code>, mas não headers HTML.

Nota: Esta opção não funciona juntamente com a opção -r.

-w

Mostra o fonte sem comentários e espaços em branco.

Nota: Esta opção não funciona juntamente com a opção -r.

-f

Interpreta e executa o arquivo informado com a opção -f Esta diretiva é opcional e pode ser deixada de lado. Informar somente o nome do arquivo para execução é suficiente.

-v

Imprime as versões o PHP, PHP SAPI e Zend para a saída padrão, por exemplo:
$ 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

-c

Esta opção informa um diretório onde procurar pelo php.ini ou especifica um arquivo INI personalizado diretamente (não presisa ser obrigatoriamente php.ini), por exemplo:
$ php -c /custom/directory/ my_script.php

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

-a

Executa o PHP no modo interativo.

-d

Esta opção permite definir um valor personalizado para qualquer diretiva de configuração permitida no php.ini. Sintaxe:
-d diretiva[=valor]

Examples:
# 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"

-e

Gera informações estendidas para o debugador/profiler.

-z

Carrega a extensão Zend. Se somente o nome de arquivo é fornecido, o PHP tenta carregar essa extensão do caminho default de bibliotecas do seu sistema (geralmente especificado em /etc/ld.so.conf em sistemas Linux). Passando um nome de arquivo com o caminho absoluto irá evitar a procura no caminho das bibliotecas de sistema. Um nome de arquivo com uma informação de diretório relativa fará com que o PHP apenas tente carregar a extensão no caminho relativo ao diretório atual.

-l

Esta opção fornece uma maneira conveniente apenas realizar uma checagem de sintaxe no código PHP fornecido. No sucesso, o texto No syntax errors detected in <arquivo> é impresso na saída padrão e informado o código de saida de sistema 0. Em caso de erro, o texto Errors parsing <filename> juntamente com o a mensagem do interpretador interno é impressa para a saída padrão e o código de saída de sistema é 255.

Esta opção não procura por erros fatais (como funções não definidas). Use -f se você deseja detectar erros fatais também.

Nota: Esta opção não trabalha com a opção -r

-m

Utilizando essa opção, o PHP imprime os módulos PHP e Zend compilados (e carregados):
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-i Esta opção de linha de comando chama a função phpinfo() e imprime seus resultados. Se o PHP não está funcionando bem, é interessante fazer um php -i para observar qualquer mensagem de erro impressa antes ou dentro das tabelas de informação. Como a saída é em HTML, ela é um pouco grande.
-r

Esta opção permite a execução de código PHP direto da linha de comando. As tags de início e fim do PHP (<?php e ?>) não são necessárias e causarão erros de interpretação.

Nota: Cuidados deverão ser tomados utilizando dessa forma para evitar que haja substituição de variáveis pelo shell.

Exemplo mostrando um erro de interpretação
$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='
O problema aqui decorre do sh/bash realizar substituições de variáveis sempre quando se utilizam aspas ("). Desde que a variável $foo não deve estar definida, ela é substituída por nada o que faz que o código passado para o PHP para execução seja:
$ php -r " = get_defined_constants();"
A maneira correta é utilizar apóstrofos ('). Variáveis em strings delimitadas por apóstrofos não são substituidas pelo sh/bash.
$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]
Se você estiver utilizando um shell diferente do sh/bash, você pode experimentar comportamentos diferenciados. Sinta-se livre para abrir um aviso de bug ou enviar um e-mail para phpdoc@lists.php.net. Você vai rapidamente conseguir problemas quando tentar obter variáveis do ambiente dentro do código ou quando utilizar barras invertidas para escape. Esteja avisado.

-h Com essa opção, você pode obter informações sobre a lista atual de opções de linha de comando pequenas descrições sobre o que elas fazem.

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:

Exemplo 24-1. Um script para rodar na linha de comando (script.php)

#!/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:

Exemplo 24-2. Arquivo batch para rodar um script em linha de comando (script.bat)

@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.