<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.7 Maintainer: alan_dangelo  Status: ready -->
<!-- 
   TODO:
   
     The command line options not in the
     list, but in the -h output below:
   
       -f, -e, -z, -l
    
     It would be best to document these, and
     collect more info about -c and -d!
-->
<appendix id="commandline">
 <title>Usare PHP alla linea di comando</title>
 <para>
  Le opzioni alla linea di comando dell'eseguibile PHP sono 
  utili nel caso si voglia fare il debug o testare il setup
  di PHP, ma possono anche essere importanti nel caso in cui si
  voglia utilizzare PHP per uno scopo diverso dallo scripting 
  per il Web.
 </para>
 <para>
  Nota,  sempre possibile dirigere l'output dell'eseguibile PHP
  verso un file esterno con il carattere &gt;, in modo che
  <literal>php -q test.php > test.html</literal> stampi come
  output di <filename>test.php</filename> il file <filename>
  test.html</filename> nella stessa directory senza header HTTP.
 </para>
 <para>
  Le opzioni alla linea di comando si possono utilizzare unicamente
  con l'eseguibile PHP. Compilando PHP come modulo per il server,
  non si avr a disposizione la versione CGI, e quindi non  possibile 
  utilizzare queste opzioni.
  Per gli utenti Windows sia l'eseguibile PHP, che il modulo per il server
  sono presenti nella distribuzione binaria, l'eseguibile si chiama
  <filename>php.exe</filename>.
 </para>
 <para>
  Questa lista di opzioni alla linea di comando  relativa a PHP 4.0.6.
  Si pu ottenere l'elenco attuale dei parametri disponibili con relativa descrizione
  con l'opzione <literal>-h</literal>. L'output di
  <literal>php -h</literal>  qualcosa di simile a questo:
  <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>
  Ora vengono elencate alcune delle opzioni pi importanti di PHP alla
  linea di comando con le relative spiegazioni.
 </para>
 <para>
  <table>
   <title>Opzioni alla linea di comando</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Opzioni</entry>
      <entry>Descrizione</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>-q</entry>
      <entry>
       Sopprime gli header HTTP dall'output. Normalmente PHP 
       stampa gli header HTTP per il programma chiamante (es. webserver)
       che poi li passa al browser. Per ci che riguarda le applicazioni
       alla riga di comando queste intestazioni sono inutili.
      </entry>
     </row>
     <row>
      <entry>-s</entry>
      <entry>
       Mostra (produce) il codice sorgente del file richiamato
       colorandone la sintassi. Si ottiene lo stesso risultato
       che si sarebbe ottenuto utilizzando la funzione 
       <function>highlight_file</function> in un normale
       script PHP.
      </entry>
     </row>
     <row>
      <entry>-v</entry>
      <entry>
       Chiamando PHP con questa opzione, si
       ottiene la stampa del suo numero di versione, es: 4.0.6. 
      </entry>
     </row>
     <row>
      <entry>-C</entry>
      <entry>
       Normalmente PHP cambia la directory di lavoro nella
       direcrory in cui si esegue lo script. Questo permette
       per esempio di poter aprire file nella stessa directory
       specificandone solamente il nome. Per disabilitare questo
       comportamento si pu usare questa opzione.
      </entry>
     </row>
     <row>
      <entry>-c</entry>
      <entry>
       Si usa questa opzione, se si vuole specificare un
       path alternativo per <filename>php.ini</filename>,
       in questo modo PHP cerca il file di configurazione
       nel percorso specificato invece che in quello di default.
      </entry>
     </row>
     <row>
      <entry>-d</entry>
      <entry>
       Con questa opzione si possono settare individualmente i 
       parametri di <filename>php.ini</filename> nel momento
       dell'esecuzione dello script.
      </entry>
     </row>
     <row>
      <entry>-m</entry>
      <entry>
       L'opzione stampa l'elenco dei moduli PHP e Zend
       disponibili, il numero della versione di PHP e Zend,
       e una piccolo avviso di copyright Zend.
      </entry>
     </row>
     <row>
      <entry>-i</entry>
      <entry>
       Questa opzione richiama <function>phpinfo</function>,
       e ne stampa i risultati. Se PHP non funziona bene,
        consigliabile utilizzare <literal>php -i</literal>
       e guardare se qualche messaggio di errore  stampati
       prima o al posto delle classiche tabelle informative.
      </entry>
     </row>
     <row>
      <entry>-h</entry>
      <entry>
       Con questa opzione, si ottengono informazioni
       sull'attuale lista di opzioni alla linea di comando,
       pi una riga di descrizione sulla funzione del parametro.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </para>
 <para>
  L'eseguibile PHP pu essere usato per creare script assolutamente
  indipendenti dal web server. Se siete su un sistema UNIX, 
  bisogna aggiungere come prima riga dello script un'intestazione
  speciale che lo rende eseguibile. Su una piattaforma Window 
  si pu associare <literal>php.exe -q</literal> all'estenzione
  <literal>.php</literal>, o creare dei file batch funzionanti
  con PHP. La prima riga che si inserisce negli script UNIX non 
  d problemi su Window, quindi  possibile scrivere programmi 
  trasversali indipendenti dalla piattaforma. Un semplice esempio
  di scrittura di un programma alla riga di comando PHP,  disponibile
  qui sotto.
 </para>
 <example>
  <title>Script utilizzati alla linea di comando (script.php)</title>
  <programlisting role="php">
<![CDATA[
#!/usr/bin/php -q
<?php

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

Questo script PHP utilizzabile alla linea di comando accetta un'opzione.

  Utilizzo:
  <?php echo $argv[0]; ?> <option>

  <option> pu essere una parola che si vuole
  stampare. Con l'opzione --help, -help, -h,
  or -?, si ottiene questo help.

<?php
} else {
    echo $argv[1];
}
?>
]]>
  </programlisting>
 </example>
 <para>
  Nello script sopra, abbiamo utilizzato come prima riga una speciale intestazione,
  che indica che il file deve essere eseguito da PHP e non deve stampare header HTTP.
  Ci sono 2 variabili che si possono utilizzare scrivendo applicazioni alla linea di
  comando con PHP: <varname>$argc</varname> e <varname>$argv</varname>. La prima
  rappresenta il numero di argomenti pi uno (il nome dello script in esecuzione)
  Il secondo  un array contenente gli argomenti, che ha come primo elemento, il 
  numero zero, il nome dello script (<varname>$argv[0]</varname>).
 </para>
 <para>
  Nel programma sopra si controlla se viene passato almeno un argomento
  allo script. Se l'argomento  <literal>--help</literal>, <literal>-help</literal>, 
  <literal>-h</literal> o <literal>-?</literal>, viene stampato un messaggio di
  aiuto, cio il nome dello script. Se viene ricevuto un argomento inaspettato,
  viene stampato all'output.
 </para>
 <para>
  Per rendere eseguibile lo script su Unix, bisogna renderlo eseguibile,
  e richiamarlo semlicemente con <literal>script.php echothis</literal>
  or <literal>script.php -h</literal>. Con Windows,  possibile creare
  un file batch per questa operazione:
 </para>
 <example>
  <title>File Batch file che eseguono script PHP alla linea di comando (script.bat)</title>
  <programlisting role="winbat">
@c:\php\php.exe -q script.php %1 %2 %3 %4
  </programlisting>
 </example>
 <para>
  Assumendo che il nome del programma sia
  <filename>script.php</filename>, e che il file
  <filename>php.exe</filename> si trovi in
  <filename>c:\php\php.exe</filename> il file batch
  funzioner con le opzioni
  <literal>script.bat echothis</literal> o
  <literal>script.bat -h</literal>.
 </para>
</appendix>

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