Capítulo 23 . Utilizando o PHP na linha de comando

A partir 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 indica , 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 SAPI s 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 SAPI s :



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 :














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

  1. Chamando o PHP para executar um arquivo determinado .

    
    
    
    
    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 .

    
    
    
    
    É 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 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 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 , 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 :




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 23-3 . Opções de linha de comando

Opção Descrição

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 .

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

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

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 .

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





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 :






Executa o PHP no modo interativo .

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

 
-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

 
"





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

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 .

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

Utilizando essa opção , o PHP imprime os módulos PHP e Zend compilados ( e carregados ) :






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

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








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:



A maneira correta é utilizar apóstrofos ( ' ). Variáveis em strings delimitadas por apóstrofos não são substituidas pelo sh/bash.



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.

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 23-1 . Um script para rodar na linha de comando ( script.php )





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