ae Mon May 13 22:43:59 2002 EDT
Added files:
/phpdoc-pt_BR/features commandline.xml
Log:
initial translation
Index: phpdoc-pt_BR/features/commandline.xml
+++ phpdoc-pt_BR/features/commandline.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.3 Maintainer: andre_ae Status: ready -->
<chapter id="features.commandline">
<title>Usando o PHP na linha de comando</title>
<!-- NEW DOCUMENTATION STARTS -->
<para>
Desde a versão 4.3, o <literal>PHP</literal> suporta um novo tipo
<literal>SAPI</literal> (Server Application Programming Interface)
chamado <literal>CLI</literal> que significa <emphasis>Command Line
Interface</emphasis>. Como o próprio nome diz, essa <literal>SAPI</literal>
tem foco no desenvolvimento de aplicações shell (ou no terminal/linha de comando) com
o <literal>PHP</literal>. As diferenças entre a
<literal>CLI SAPI</literal> e as outras <literal>SAPI</literal>s são
detalhadas neste capítulo.
</para>
<para>
A <literal>CLI SAPI</literal> foi liberada primeiramente com o
<literal>PHP 4.2.0</literal>, mas ainda em estágio experimental, sendo necessário
ativá-la explicitamente com a opção <literal>--enable-cli</literal> durante o
<literal>./configure</literal>. Desde o <literal>PHP 4.0.3</literal> a
<literal>CLI SAPI</literal> não mais é experimental e é
<emphasis role="strong">sempre</emphasis> compilada e instalada como o arquivo
<filename>php</filename> (chamado <filename>php.exe</filename> no Windows),
no formato binário executável.
</para>
<para>
Diferenças importantes das <literal>CLI SAPI</literal> comparada com outras
<literal>SAPI</literal>s:
<itemizedlist>
<listitem>
<para>
Diferentemente da <literal>CGI SAPI</literal>, nenhum header é impresso
na saída.
</para>
<para>
A <literal>CGI SAPI</literal> possui um meio de suprimir os headers
HTTP, mas não há uma chave equivalente para ativá-los na <literal>CLI
SAPI</literal>.
</para>
</listitem>
<listitem>
<para>
Estas são as diretivas do &php.ini; que são sobrescritas pela <literal>CLI
SAPI</literal> porque não fazem sentido no ambiente shell:
<table>
<title>Diretivas &php.ini; sobrescritas</title>
<tgroup cols="3">
<thead>
<row>
<entry>Diretiva</entry>
<entry>Valor default <literal>CLI SAPI</literal></entry>
<entry>Comentários</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend="ini.html-errors">html_errors</link></entry>
<entry>&false;</entry>
<entry>
Pode ser bem difícil de ler mensagens de erro no seu shell quando
elas estão embebidas dentro de tags <literal>HTML</literal>,
por isso essa diretiva tem default para &false;.
</entry>
</row>
<row>
<entry><link linkend="ini.implicit-flush">implicit_flush</link></entry>
<entry>&true;</entry>
<entry>
Essa diretiva causa que qualquer saída gerada de um
<function>print</function>, <function>echo</function> e semelhantes sejam
imediatamente escritas para o output e não cacheadas em nenhum buffer.
</entry>
</row>
<row>
<entry><link
linkend="ini.max-execution-time">max_execution_time</link></entry>
<entry>0 (unlimited)</entry>
<entry>
Devido as infinitas possibilidades da utilização do <literal>PHP</literal> 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.
</entry>
</row>
<row>
<entry><link
linkend="ini.register-argc-argv">register_argc_argv</link></entry>
<entry>&true;</entry>
<entry>
As variáveis globais do <literal>PHP</literal> <literal>$argc</literal>
(número de argumentos passados para aplicação) e
<literal>$argv</literal> (array com os argumentos atuais) são sempre
presentes e preenchidos com os valores apropriados quando utilizando a
<literal>CLI SAPI</literal>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<para>
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, <link linkend="ini.register-argc-argv">register_argc_argv</link>).
</para>
</note>
</listitem>
<listitem>
<para>
A <literal>CLI SAPI</literal> <emphasis
role="strong">não</emphasis> modifica o diretório de execução atual para o
diretório
onde o script é interpretado!
</para>
<para>
Exemplo mostrando a diferença da <literal>CGI SAPI</literal>:
<programlisting role="php">
<![CDATA[
<?
/* Nossa aplicação de teste */
echo getcwd(), "\n";
?>
]]>
</programlisting>
</para>
<para>
Quando utilizando a versão <literal>CGI</literal>, a saída é
<screen>
<![CDATA[
$ pwd
/tmp
$ php-cgi -f outro_diretorio/test.php
/tmp/outro_diretorio
]]>
</screen>
Isto mostra como o <literal>PHP</literal> modifica o diretório atual
para aquela onde o script é executado.
</para>
<para>
Utilizando a versão <literal>CLI SAPI</literal>:
<screen>
<![CDATA[
$ pwd
/tmp
$ php -f outro_diretorio/test.php
/tmp
]]>
</screen>
E isto mostra a grande flexibilidade ferramentas shell em
<literal>PHP</literal>.
</para>
<note>
<para>
A <literal>CGI SAPI</literal> suporta o comportamento da <literal>CLI
SAPI</literal>
utilizando a chave <literal>-C</literal> quando de sua execução na
linha de comando.
</para>
</note>
</listitem>
</itemizedlist>
</para>
<para>
A lista de opções de linha de comando fornecidas pelo binário do
<literal>PHP</literal>
pode ser solicitada a qualquer tempo executando o <literal>PHP</literal> com a
opção <literal>-h</literal>:
<screen>
<![CDATA[
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
]]>
</screen>
</para>
<para>
A <literal>CLI SAPI</literal> fornecer três maneiras diferentes para você
executar seu código <literal>PHP</literal>:
<orderedlist>
<listitem>
<para>
Chamando o <literal>PHP</literal> para executar um arquivo determinado.
</para>
<para>
<screen>
<![CDATA[
php my_script.php
php -f my_script.php
]]>
</screen>
De ambas maneiras (utilizando ou não a opção <literal>-f</literal>) o
arquivo informado <filename>my_script.php</filename> é executado. Você pode
escolher qualquer arquivo para
executar, seus scripts <literal>PHP</literal> não precisam terminar com a
extensão <filename>.php</filename>, podendo ter qualquer nome ou extensão
que você deseje.
</para>
</listitem>
<listitem>
<para>
Passar o código <filename>PHP</filename> para execução diretamente a linha
de comando.
</para>
<para>
<screen>
<![CDATA[
php -r 'print_r(get_defined_constants());'
]]>
</screen>
É preciso ter especial cuidado com a substituição de variáveis shell e
delimitação de strings utilizada.
</para>
<note>
<para>
Leia o exemplo cuidadosamente, observando que não há tags de abertura ou
fechamento! A
opção <literal>-r</literal> simplesmente não precisa delas. Utilizando-as você
obterá erros de interpretação.
</para>
</note>
</listitem>
<listitem>
<para>
Fornece código <literal>PHP</literal> para interpretação via a entrada padrão
(<literal>stdin</literal>).
</para>
<para>
Isto mostra a habilidade poderosa de como criar dinamicamente
código <literal>PHP</literal> e fornecê-lo ao binário, como demonstrado
neste exemplo (apenas demonstrativo):
<screen>
<![CDATA[
$ alguma_aplicacao | algum_filtro | php | sort -u >final_output.txt
]]>
</screen>
</para>
</listitem>
</orderedlist>
Você não pode combinar nenhum das três maneiras para executar código.
</para>
<para>
Assim como qualquer aplicação shell, não somente o binário do <literal>PHP</literal>
aceita um certo número de argumentos, mas também seu script <literal>PHP</literal>
também pode recebê-los. O número de argumentos que podem ser passados para seu script
não é limitado ao <literal>PHP</literal> (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 <literal>$argv</literal>. No índice zero sempre conterá o nome do
script (podendo ser <literal>-</literal> no caso de código <literal>PHP</literal>
estar vindo da entrada padrão ou da opção de linha de comando
<literal>-r</literal>). O segunda variável global
<literal>$argc</literal> contém o número de elementos no
array <literal>$argv</literal> (<emphasis role="strong">mas não</emphasis> o
número de argumentos passados para seu script.
</para>
<para>
Os argumentos que você deseja passar para seu script não podem começar com o caracter
<literal>-</literal> e isso não pode ser modificado.
Passando argumentos para seu script que comecem com um
<literal>-</literal> causará problemas porque o <literal>PHP</literal>
tentará manuseá-los. Para prevenir isso, utilize o separador de argumentos
<literal>--</literal>. Depois que os argumentos são interpretados pelo
<literal>PHP</literal>, todos os argumentos restantes são repassados
intocados para seu script.
</para>
<screen>
<![CDATA[
# 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"
}
]]>
</screen>
<para>
Entretanto, há ainda uma outra maneira de se utilizar o <literal>PHP</literal> no
shell. Você pode escrever um script que na primeira linha tenha
<literal>#!/usr/bin/php</literal> e na seqüência tenha
código <literal>PHP</literal> 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:
<programlisting role="php">
<![CDATA[
#!/usr/bin/php
<?
var_dump($argv);
?>
]]>
</programlisting>
Assumindo que o arquivo foi nomeado como <filename>teste</filename> e está no
diretório
atual, nós podemos fazer o seguinte:
<screen>
<![CDATA[
$ chmod 755 teste
$ ./test -h -- foo
array(4) {
[0]=>
string(6) "./teste"
[1]=>
string(2) "-h"
[2]=>
string(2) "--"
[3]=>
string(3) "foo"
}
]]>
</screen>
Como você viu, dessa forma não há problemas em passar parâmetros para seu script
que comecem com o caracter <filename>-</filename>
</para>
<para>
<table>
<title>Opções de linha de comando</title>
<tgroup cols="2">
<thead>
<row>
<entry>Opção</entry>
<entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>-s</entry>
<entry>
<para>
Mostra o código fonte com destaque de cores.
</para>
<para>
Esta opção usa o mecanismo interno para interpretar o arquivo e produzir
uma versão <literal>HTML</literal> do fonte com destaque de cores e a envia
para
a saída padrão. Note que ele somente gerará blocos de
<literal><code> [...] </code></literal>,
mas não headers <literal>HTML</literal>.
</para>
<note>
<para>
Esta opção não funciona juntamente com a opção <literal>-r</literal>.
</para>
</note>
</entry>
</row>
<row>
<entry>-w</entry>
<entry>
<para>
Mostra o fonte sem comentários e espaços em branco.
</para>
<note>
<para>
Esta opção não funciona juntamente com a opção <literal>-r</literal>.
</para>
</note>
</entry>
</row>
<row>
<entry>-f</entry>
<entry>
<para>
Interpreta e executa o arquivo informado com a opção <literal>-f</literal>
Esta diretiva é opcional e pode ser deixada de lado. Informar somente
o nome do arquivo para execução é suficiente.
</para>
</entry>
</row>
<row>
<entry>-v</entry>
<entry>
<para>
Imprime as versões o PHP, PHP SAPI e Zend para a saída padrão, por exemplo:
<screen>
<![CDATA[
$ php -v
PHP 4.3.0-dev (cli)
Zend Engine v1.2.1, Copyright (c) 1998-2002 Zend Technologies
]]>
</screen>
</para>
</entry>
</row>
<row>
<entry>-c</entry>
<entry>
<para>
Esta opção informa um diretório onde procurar pelo
&php.ini; ou especifica um arquivo <literal>INI</literal> personalizado
diretamente (não presisa ser obrigatoriamente &php.ini;), por exemplo:
<screen>
<![CDATA[
$ php -c /custom/directory/ my_script.php
$ php -c /custom/directory/custom-file.ini my_script.php
]]>
</screen>
</para>
</entry>
</row>
<row>
<entry>-a</entry>
<entry>
<para>
Executa o <literal>PHP</literal> no modo interativo.
<!--
mfischer, 20020510: Couldn't come up with a decent useful description
of the current implementation of the interactive mode.
-->
</para>
</entry>
</row>
<row>
<entry>-d</entry>
<entry>
<para>
Esta opção permite definir um valor personalizado para qualquer diretiva
de configuração permitida no &php.ini;. Sintaxe:
<screen>
<![CDATA[
-d diretiva[=valor]
]]>
</screen>
</para>
<para>
Examples:
<screen>
<![CDATA[
# 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"
]]>
</screen>
</para>
</entry>
</row>
<row>
<entry>-e</entry>
<entry>
<para>
Gera informações estendidas para o debugador/profiler.
<!--
mfischer, 20020510: Anyone who can provide more information what it
really does (even if it's only for developers) ?
-->
</para>
</entry>
</row>
<row>
<entry>-z</entry>
<entry>
<para>
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 <filename>/etc/ld.so.conf</filename> 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 <literal>PHP</literal> apenas
tente
carregar a extensão no caminho relativo ao diretório atual.
</para>
</entry>
</row>
<row>
<entry>-l</entry>
<entry>
<para>
Esta opção fornece uma maneira conveniente apenas realizar uma checagem de
sintaxe
no código <literal>PHP</literal> fornecido. No sucesso, o texto
<literal>No syntax errors detected in <arquivo></literal> é
impresso na saída padrão e informado o código de saida de sistema
<literal>0</literal>. Em caso de erro, o texto <literal>Errors parsing
<filename></literal> juntamente com o a mensagem do interpretador
interno é impressa para a saída padrão e o código de saída de sistema é
<literal>255</literal>.
</para>
<para>
Esta opção não procura por erros fatais (como funções não definidas). Use
<literal>-f</literal> se você deseja detectar erros fatais também.
</para>
<note>
<para>
Esta opção não trabalha com a opção <literal>-r</literal>
</para>
</note>
</entry>
</row>
<row>
<entry>-m</entry>
<entry>
<para>
Utilizando essa opção, o PHP imprime os módulos PHP e Zend compilados
(e carregados):
<screen>
<![CDATA[
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype
[Zend Modules]
]]>
</screen>
</para>
</entry>
</row>
<row>
<entry>-i</entry>
<entry>
Esta opção de linha de comando chama a função <function>phpinfo</function> e
imprime
seus resultados. Se o <literal>PHP</literal> não está funcionando bem, é
interessante fazer um <literal>php -i</literal> para observar qualquer mensagem
de erro impressa antes ou dentro das tabelas de informação.
Como a saída é em <literal>HTML</literal>, ela é um
pouco grande.
</entry>
</row>
<row>
<entry>-r</entry>
<entry>
<para>
Esta opção permite a execução de código <literal>PHP</literal> direto da
linha de comando. As tags de início e fim do <literal>PHP</literal>
(<literal><?php</literal> e <literal>?></literal>)
<emphasis role="strong">não são</emphasis> necessárias e causarão erros
de interpretação.
</para>
<note>
<para>
Cuidados deverão ser tomados utilizando dessa forma para
evitar que haja substituição de variáveis pelo
shell.
</para>
<para>
Exemplo mostrando um erro de interpretação
<screen>
<![CDATA[
$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='
]]>
</screen>
O problema aqui decorre do sh/bash realizar substituições de variáveis
sempre quando se utilizam aspas (<literal>"</literal>). Desde que a
variável <literal>$foo</literal> não deve estar definida, ela é
substituída por nada o que faz que o código passado para o
<literal>PHP</literal> para execução seja:
<screen>
<![CDATA[
$ php -r " = get_defined_constants();"
]]>
</screen>
A maneira correta é utilizar apóstrofos (<literal>'</literal>).
Variáveis em strings delimitadas por apóstrofos não são substituidas
pelo sh/bash.
<screen>
<![CDATA[
$ 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"]=>
[...]
]]>
</screen>
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 [EMAIL PROTECTED]
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.
</para>
</note>
</entry>
</row>
<row>
<entry>-h</entry>
<entry>
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.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<!-- NEW DOCUMENTATION ENDS -->
<!-- OLD DOCUMENTED STARTS
mfischer, 20020510: I've commented out the start paragraphs of the old
documentation as it is meant to be replaced by the new one.
<para>
As opções de linha de comando para o executável do PHP são úteis
se você deseja debugar ou testar a instalação do PHP, mas
pode ser mais que isso, se você precisa utilizar o PHP para um
propósito diferente do script para Web.
</para>
<para>
Note que você sempre pode direcionar a saída do executável do PHP
para um arquivo externo com o caracter >,
então <literal>php -q test.php > test.html</literal>
enviará todo a saída de <filename>test.php</filename>
sem os headers HTTP para o arquivo <filename>test.html</filename>
no mesmo diretório.
</para>
<para>
Você só pode utilizar essas opções de linha de comando se você tiver
o PHP executável. Se você compilou a versão módulo
e não possui a versão CGI disponível em sua
máquina, então você não poderá usar essas opções.
Para os usuários Windows, tanto a versão executável e módulo do PHP
então na distribuição binária, onde o executável é
chamado <filename>php.exe</filename>.
</para>
<para>
A seguinte lista das opções de linha de comando está atualizada para o PHP 4.0.6.
Você pode obter a lista atualizada e algumas descrições com o opcional
<literal>-h</literal>. A saída de
<literal>php -h</literal> deverá ser algo como isso:
<screen>
<![CDATA[
Usage: php [-q] [-h] [-s [-v] [-i] [-f <file>] | {<file> [args...]}
-q Quiet-mode. Suppress HTTP Header output.
-s Display colour syntax highlighted source.
-f <file> Parse <file>. Implies `-q'
-v Version number
-C Do not chdir to the script's directory
-c <path> Look for php.ini file in this directory
-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
-h This help
]]>
</screen>
</para>
<para>
Esta é a lista das mais importantes opções de linha de comando
com explicações detalhadas.
</para>
<para>
<table>
<title>Opções de linha de comando</title>
<tgroup cols="2">
<thead>
<row>
<entry>Opção</entry>
<entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>-q</entry>
<entry>
Suprime os headers HTTP na saída. Normalmente o PHP imprime
headers HTTP para o programa chamador (normalmente o servidor web)
para encaminhar para o browser. Escrevendo aplicações
para a linha de comando esses headers são desnecessários.
</entry>
</row>
<row>
<entry>-s</entry>
<entry>
Exibe o código fonte com destaque de cores para o arquivo
interpretado com essa opção. Tem o mesmo efeito de você
exibir código fonte utilizando a função
<function>highlight_file</function> num
script PHP.
</entry>
</row>
<row>
<entry>-f</entry>
<entry>
Interpreta o arquivo informado, e procura por erros de sintaxe ou
fatais. Essa opção implica em -q. Utilize para
debugar.
</entry>
</row>
<row>
<entry>-v</entry>
<entry>
Chamando o PHP com essa opção, ele exibe
o número da sua versão, por exemplo, 4.0.6.
</entry>
</row>
<row>
<entry>-C</entry>
<entry>
Normalmente o PHP altera o diretório de trabalho para
o diretório de execução do script. Esta opção torna possível,
por exemplo, abrir arquivos no mesmo diretório,
apenas especificando o nome do arquivo. Se você
deseja desativar essa modificação de diretório, basta
usar a opção.
</entry>
</row>
<row>
<entry>-c</entry>
<entry>
Utilizando essa opção, você pode especificar um caminho alternativo
para o &php.ini;, então o PHP
procurará por seu arquivo de configurações neste caminho
em vez de seu default.
</entry>
</row>
<row>
<entry>-d</entry>
<entry>
Com essa opção, você pode configurar diretivas individuais do
&php.ini; para
execução de um script.
</entry>
</row>
<row>
<entry>-l</entry>
<entry>
Verifica o arquivo informado apenas para erros de sintaxe. Esta
opção implica em -q. Utilize para debugar.
Esta opção não verifica erros fatais (como funções
não definidas). Utilize -f para testar
erros fatais também.
</entry>
</row>
<row>
<entry>-m</entry>
<entry>
Utilizando esta opção, o PHP imprime a lista dos módulos PHP e Zend
compilados (e carregados), as versões do PHP e
Zend e uma pequena informação de copyright
da Zend.
</entry>
</row>
<row>
<entry>-i</entry>
<entry>
Esta opção chama a função
<function>phpinfo</function> e imprime
seus resultados. Se o PHP não estiver funcionando bem,
é interessante que você faça um <literal>php -i</literal>
e você verá qualquer mensagem de erro exibida
antes da tabela de informações.
</entry>
</row>
<row>
<entry>-h</entry>
<entry>
Com essa opção você pode obter informações sobre
a atual lista de opções de linha de comando e
pequenas descrições dessas opções.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
-->
<para>
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 <literal>php.exe -q</literal> com o clique duplo em arquivos
<literal>.php</literal> 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:
</para>
<example>
<title>Um script para rodar na linha de comando (script.php)</title>
<programlisting role="php">
<![CDATA[
#!/usr/bin/php -q
<?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];
}
?>
]]>
</programlisting>
</example>
<para>
No script acima, nós utilizamos uma primeira linha especial para indicar
que este arquivo precisa rodar pelo PHP e que não deve imprimir headers
HTTP. Há duas variáveis que você precisa conhecer para escrever aplicações
em linha de comando com o PHP: <varname>$argc</varname> e
<varname>$argv</varname>. 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 (<varname>$argv[0]</varname>).
</para>
<para>
No programa acima é verificado se há apenas um argumento
fornecido. Se o argumento for <literal>--help</literal>,
<literal>-help</literal>, <literal>-h</literal> ou <literal>-?</literal>,
é impresso uma mensagem de ajuda, imprimindo o nome do script dinamicamente.
Qualquer outro argumento é exibido como informado.
</para>
<para>
Para rodar esse aplicativo nos Unix, basta torná-lo
executável e o chamar diretamente como
<literal>script.php exibaisso</literal> ou
<literal>script.php -h</literal>. No Windows, você pode fazer um
arquivo batch para esta tarefa:
</para>
<example>
<title>Arquivo batch para rodar um script em linha de comando (script.bat)</title>
<programlisting role="winbat">
@c:\php\php.exe -q script.php %1 %2 %3 %4
</programlisting>
</example>
<para>
Assumindo que você nomeou o programa acima como
<filename>script.php</filename>, e você tem um
<filename>php.exe</filename> em
<filename>c:\php\php.exe</filename> este arquivo batch
irá rodar com os seguintes parâmetros:
<literal>script.bat exibaisso</literal> ou
<literal>script.bat -h</literal>.
</para>
<para>
Veja também a documentação da extensão <link linkend="ref.readline">Readline</link>
para mais funções que você pode usar
para incrementar suas aplicações para linha de comando em PHP.
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
