<?xml version="1.0" encoding="utf-8"?>

<chapter xml:id="features.commandline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<title>Utilizzo di PHP da linea di comando</title>

<titleabbrev>Command line usage</titleabbrev>

<!--Introduction: {{{-->

<section xml:id="features.commandline.introduction">

<title>Introduzione</title>

<para>

L'obiettivo principale di &cli.sapi;

è quello di sviluppare applicazioni shell con PHP. Esistono

alcune differenze tra la &cli.sapi; e le altre

<acronym>SAPI</acronym>; queste saranno illustrate nel corrente capitolo. Val la pena

ricordare che &cli; e <acronym>CGI</acronym> sono differenti

<acronym>SAPI</acronym> sebbene condividano il medesimo comportamento in diverse situazioni.

</para>

<para>

La &cli.sapi; è abilitata di default con l'opzione

<option role="configure">--enable-cli</option>, ma può esseredisattivata usando

<option role="configure">--disable-cli</option> quando si usa il comando

<command>./configure</command>.

</para>

<para>

Il nome, la posizione, e l'esistenza di eseguibili &cli;/<acronym>CGI</acronym>

differiranno in base a come il PHP sarà installato sul sistema. Per

default quando si esegue il <command>make</command>, si compila sia la versione <acronym>CGI</acronym>

sia la versione &cli; e saranno poste rispettivamente in <filename>sapi/cgi/php-cgi</filename> e

<filename>sapi/cli/php</filename> a partire dalla directory dei sorgenti.

Occorre notare che entrambi gli eseguibili sono chiamati <literal>php</literal>. Ciò che accade durante

l'esecuzione di <command>make install</command> dipende dalla linea di configurazione. Se durante

la configurazione si è scelto un modulo <acronym>SAPI</acronym>, tipo apxs, o si è attivato

<option role="configure">--disable-cgi</option>, l'eseguibile &cli; viene

copiato in <filename>{PREFIX}/bin/php</filename>

durante <command>make install</command>, altrimenti in questa cartella sarà posto l'eseguibile

<acronym>CGI</acronym>. Così, per esempio, se si ha come parametro di configurazione

<option role="configure">--with--apxs</option> allora l'eseguibile &cli; sarà copiato in <filename>{PREFIX}/bin/php

</filename> durante <command>make install</command>. Se si vuole evitare

l'installazione dell'eseguibile <acronym>CGI</acronym>, utilizzare <command>make

install-cli</command> dopo <command>make install</command>. In alternativa

si può specificare <option role="configure">--disable-cgi </option> nella linea di

configurazione.

</para>

<note>

<para>

Poiché sia <option role="configure">--enable-cli</option> sia

<option role="configure">--enable-cgi</option> sono abilitati per default,

avere semplicemente <option role="configure">--enable-cli</option> nella linea

di configurazione non significa necessariamente che l'eseguibile &cli; sia copiato come

<filename>{PREFIX}/bin/php</filename> con l'esecuzione di <command>make install</command>.

</para>

</note>

<para>

La versione &cli; viene inserita nella cartella principale, con il nome <filename>

php.exe</filename> in Windows. La versione <acronym>CGI</acronym> è

chiamata <filename>php-cgi.exe</filename>. Inoltre, è distribuito un file chiamato <filename>

php-win.exe</filename> se PHP è configurato con

<option role="configure">--enable-cli-win32</option>. Questo è equivalente alla

versione &cli;, tranne che php-win non visualizzerà nulla

e quindi non vi sarà la finestra di console.

</para>

<note>

<title>Quale SAPI ho?</title>

<para>

Da shell, digitando <command>php -v</command> si avrà l'informazione di

quale <filename>php</filename> si tratta, <acronym>CGI</acronym> o &cli;. Vedere

anche la funzionei <function>php_sapi_name</function> e la costante

<constant>PHP_SAPI</constant> per dettagli.

</para>

</note>

<note>

<para>

Una pagina stile <literal>man</literal> di Unix è disponibile digitando <command>man

php</command> da linea di comando.

</para>

</note>

</section>

<!--}}}-->

<!--Differences: {{{-->

<section xml:id="features.commandline.differences">

<title>Differenze con gli altri <acronym>SAPI</acronym></title>

<para>

Le principali differenze tra la &cli; <acronym>SAPI</acronym> e le altre

<acronym>SAPI</acronym> sono:

<itemizedlist>

<listitem>

<para>

A differenza di <acronym>CGI</acronym> <acronym>SAPI</acronym>, non sono inviate in output

delle intestazioni.

</para>

<para>

Mentre nella <acronym>CGI</acronym> <acronym>SAPI</acronym> esiste un modo per sopprimere

le intestazioni HTTP, nella &cli.sapi; non si ha una opzione

per abilitare le intestazioni.

</para>

<para>

Per default &cli; parte in modalità silenziosa, si è mantenuto, comunque,

l'opzione <option>-q</option> e <option>--no-header</option> per motivi di compatibilità;

in questo modo si possono utlizzare i vecchi script <acronym>CGI</acronym>.

</para>

<para>

Non cambia la directory di lavoro in quella dello script.

(È rimasta l'opzione <option>-C</option> e <option>--no-chdir</option> per

compatibilità)

</para>

<para>

Messaggi di errore in formato testo (non formattati in <acronym>HTML</acronym>).

</para>

</listitem>

<listitem>

<para>

Esistono alcune direttive del &php.ini; che sono forzate nell'impostazione dalla

&cli.sapi; poiché non hanno senso nell'ambiente di shell:

</para>

<para>

<table>

<title>Direttive del &php.ini; forzate</title>

<tgroup cols="3">

<thead>

<row>

<entry>Direttiva</entry>

<entry>&cli; <acronym>SAPI</acronym> valore di default</entry>

<entry>Commento</entry>

</row>

</thead>

<tbody>

<row>

<entry><link linkend="ini.html-errors">html_errors</link></entry>

<entry>&false;</entry>

<entry>

Il valore predefinito è &false;, dato che è difficile leggere i messaggi di errore

nell'ambiente shell quando sono affogati in tag <acronym>HTML</acronym>

non interpretati.

</entry>

</row>

<row>

<entry><link linkend="ini.implicit-flush">implicit_flush</link></entry>

<entry>&true;</entry>

<entry>

In un ambiente shell, è desiderabile che ogni tipo di output proveniente da

<function>print</function>, <function>echo</function> e simili sia scritto

immediatamente e non venga bufferizzato.

Tuttavia è ancora possibile utilizzare le funzioni di

<link linkend="ref.outcontrol">buffering dell'output</link>

se si desidera ritardare o manipolare lo standard output.

</entry>

</row>

<row>

<entry><link linkend="ini.max-execution-time">max_execution_time</link></entry>

<entry>0 (unlimited)</entry>

<entry>

PHP nell'ambiente di shell tende ad essere utilizzato per una gamma di scopi molto

diverso dalle applicazioni per il Web, e questi possono

avere tempi di esecuzione molto lunghi; Il tempo massimo di esecuzione è impostato a infinito.

</entry>

</row>

<row>

<entry><link linkend="ini.register-argc-argv">register_argc_argv</link></entry>

<entry>&true;</entry>

<entry>

<para>

Impostare questo parametro a &true; significa che gli script eseguiti attraverso

la &cli; <acronym>CLI SAPI</acronym> hanno sempre accesso a

<emphasis>argc</emphasis> (numero di argomenti passati

all'applicazione) e <emphasis>argv</emphasis> (matrice degli

argumenti).

</para>

<para>

Le variabili PHP <varname>$argc</varname>

e <varname>$argv</varname> sono automaticamente impostate ai valori

appropriati quando si usa la &cli; <acronym>SAPI</acronym>. Questi valori possono

anche essere trovati nell'array <varname>$_SERVER</varname>, per esempio:

<varname>$_SERVER['argv']</varname>

</para>

</entry>

</row>

<row>

<entry><link linkend="ini.output-buffering">output_buffering</link></entry>

<entry>&false;</entry>

<entry>

<para>

Anche se il parametro nel &php.ini; è impostato a &false;, le funzioni

<link linkend="book.outcontrol">Output buffering</link>

sono disponibili.

</para>

</entry>

</row>

<row>

<entry><link linkend="ini.max-input-time">max_input_time</link></entry>

<entry>&false;</entry>

<entry>

<para>

La &cli; PHP non accetta GET, POST o upload di file.

</para>

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<note>

<para>

Queste direttive non possono essere inizializate con altri valori

dal file di configurazione &php.ini; o da uno personalizzato (se specifictao). Questa è

una limitazione perché questi valori di default sono applicati

dopo avere esaminato tutti i file di configurazione. Tuttavia i loro valori possono

essere cambiati durante l'esecuzione (operazione che non ha senso per queste direttive,

ad esempio <link linkend="ini.register-argc-argv">register_argc_argv</link>).

</para>

</note>

<note>

<para>

It is recommended to set

<link linkend="ini.ignore-user-abort">ignore_user_abort</link> for

command line scripts. See <function>ignore_user_abort</function> for

more information.

</para>

</note>

</listitem>

<listitem>

<para>

Per potere lavorare meglio con le shell, sono state definite delle costanti

per <link linkend="features.commandline.io-streams">gli stream I/O

</link>.

</para>

</listitem>

<listitem>

<para>

La &cli.sapi; <emphasis role="strong">non</emphasis> cambia la

directory corrente in quella dello script eseguito!

</para>

<example>

<title>

Il seguente esempio illustra la diferenza rispetto alla <acronym>CGI</acronym>

<acronym>SAPI</acronym>:

</title>

<programlisting role="php">

</programlisting>

<para>

Quando si usa la versione <acronym>CGI</acronym>, si avrà il seguente output:

</para>

<screen>

</screen>

<para>

Questo evidenzia chiaramente come il PHP cambi la

directory corrente con quella in cui si trova lo script.

</para>

<para>

Utilizzando la versione &cli.sapi; abbiamo:

</para>

<screen>

</screen>

<para>

Questo permette una grande flessibilità nello scrivere tools in PHP.

</para>

</example>

<note>

<para>

La <acronym>CGI</acronym> <acronym>SAPI</acronym> supporta il comportamento

della &cli.sapi; attivando l'opzione <option>-C</option>

quando viene eseguito da linea di comando.

</para>

</note>

</listitem>

</itemizedlist>

</para>

</section>

<!--}}}-->

<!--Options: {{{-->

<section xml:id="features.commandline.options">

<title>Opzioni della linea di comando</title>

<titleabbrev>Opzioni</titleabbrev>

<para>

L'elenco completo delle opzioni del PHP disponibili da linea di comando

può essere visualizzato in qualsiasi momento eseguendo il PHP con l'opzione <option>-h</option>:

<screen>

</screen>

</para>

<para>

<table>

<title>Opzioni della linea di comando,</title>

<tgroup cols="2">

<thead>

<row>

<entry>Parametro</entry>

<entry>Parametro lungo</entry>

<entry>Descrizione</entry>

</row>

</thead>

<tbody>

<row>

<entry>-a</entry>

<entry>--interactive</entry>

<entry>

<para>

Esegue il PHP in modo interattivo. Per maggiori informazioni, vedere la sezione <link

linkend="features.commandline.interactive">Shell interattiva</link>

.

</para>

</entry>

</row>

<row>

<entry>-b</entry>

<entry>--bindpath</entry>

<entry>

<para>

Percorso per collegamento esterno alla modalità Server FASTCGI (solo

<acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-C</entry>

<entry>--no-chdir</entry>

<entry>

<para>

Non eseguire chdir nella cartella dello script (solo <acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-q</entry>

<entry>--no-header</entry>

<entry>

<para>

Modo silenzioso. Sopprime l'emissione delle intestazioni <acronym>HTTP</acronym>

(solo <acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-T</entry>

<entry>--timing</entry>

<entry>

<para>

Misura il tempo di esecuzione dello script ripetuto<varname>count</varname>

volte (solo <acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-c</entry>

<entry>--php-ini</entry>

<entry>

<para>

Con questa opzione si può sia specificare la directory in cui cercare

il &php.ini; o si può specificare un file <literal>INI</literal> personalizzato

(che non deve necessariamente chiamarsi &php.ini;), ad esempio:

</para>

<para><informalexample>

<screen>

</screen>

</informalexample></para>

<para>

Se non si specifica questa opzione, il file viene ricercato nelle

<link linkend="configuration.file">directory di default</link>.

</para>

</entry>

</row>

<row>

<entry>-n</entry>

<entry>--no-php-ini</entry>

<entry>

<para>

Ignora del tutto il &php.ini;.

</para>

</entry>

</row>

<row>

<entry>-d</entry>

<entry>--define</entry>

<entry>

<para>

Questa opzione permette di impostare valori personalizzati per qualsiasi

delle direttive di configurazione previste in &php.ini;. La sintassi è:

<screen>

<![CDATA[

</screen>

</para>

<para><example>

<title>Example of using <literal>-d</literal> to set an INI setting</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-e</entry>

<entry>--profile-info</entry>

<entry>

<para>

Genera informazioni estese per il

debugger/profiler.

</para>

</entry>

</row>

<row>

<entry>-f</entry>

<entry>--file</entry>

<entry>

<para>

Analizza ed esegue il file passato con l'opzione <option>-f</option>.

Questo parametro è opzionale e può essere omesso. Basta fornire il

nome del file da eseguire.

</para>

<note>

<para>

Al fine di passare argomenti ad uno script, il primo argomento deve essere

<literal>--</literal>, altrimenti PHP li interpreterà come opzioni

del PHP.

</para>

</note>

</entry>

</row>

<row>

<entry>-h e -?</entry>

<entry>--help e --usage</entry>

<entry>

Con questa opzione si ha l'elenco dei comandi di linea

ed una breve descrizione di questi.

</entry>

</row>

<row>

<entry>-i</entry>

<entry>--info</entry>

<entry>

Questa opzione della linea di comando richiama la funzione <function>phpinfo</function>, e ne

visualizza il risultato. Se il PHP non funziona correttamente, è opportuno

utilizzare <command>php -i</command> per verificare se sono visualizzati messaggi di errore

prima o al posto della tabella con le informazioni.

Fare attenzione quando si usa la modalità <acronym>CGI</acronym>, l'output è in formato <acronym>HTML</acronym> e quindi abbastanza

abbondante.

</entry>

</row>

<row>

<entry>-l</entry>

<entry>--syntax-check</entry>

<entry>

<para>

Questa opzione fornisce un metodo pratico per eseguire un controllo sintattico

di un dato codice PHP. Se il controllo ha successo, verrà visualizzato il testo

<literal>No syntax errors detected in &lt;filename&gt;</literal>

e alla shell sarà restituito il codice

<literal>0</literal>. Se si rilevano errori si avrà il testo <literal>Errors parsing

&lt;filename&gt;</literal>, inoltre si avranno anche i messaggi di errore del parser

ed alla shell sarà restituito il codice

<literal>-1</literal>.

</para>

<para>

Questa opzione non rileva errori fatali (tipo funzioni non definite). Occorre

utilizzare l'opzione <option>-f</option> se si desidera rilevare gli errori fatali.

</para>

<note>

<para>

Questa opzione non è abbinabile all'opzione

<option>-r</option>.

</para>

</note>

</entry>

</row>

<row>

<entry>-m</entry>

<entry>--modules</entry>

<entry>

<para><example>

<title>Visualizzazione dei moduli PHP e di Zend integrati (e quindi caricati):</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-r</entry>

<entry>--run</entry>

<entry>

<para>

Questa opzione permette l'esecuzione di codice PHP direttamente da linea di comando.

I tag PHP di apertura e di chiusura (<literal>&lt;?php</literal> e

<literal>?&gt;</literal>) <emphasis role="strong">non sono

necessari</emphasis> anzi, se presenti, causano un errore del parser.

</para>

<note>

<para>

Quando si utilizza questo metodo occorre prestare attenzione ad evitare

collisioni con la sostituzione delle varibili eseguita dalla shell

sulla linea di comando.

</para>

<example>

<title>errore di sintassi con l'utilizzo dei doppi apici</title>

<screen>

</screen>

</example>

<para>

In questo caso il problema è dovuto alla sostituzione della variabile

eseguita da sh/bash anche quando si usano i doppi apici <literal>"</literal>.

Poiché la variabile <varname>$foo</varname> non è definita, essa

verrà espansa con 'niente' generando il seguente codice

PHP:

</para>

<informalexample>

<screen>

</screen>

</informalexample>

<para>

Il metodo corretto richiede l'uso dell'apice singolo <literal>'</literal>.

Le variabili racchiuse in stringhe delimite dall'apice singolo non

vengono espanse da sh/bash.

</para>

<example>

<title>Utilizzo degli apici singoli per impedire la sostituzione delle variabili

nella shell</title>

<screen>

</screen>

</example>

<para>

Se si utilizzano shell differenti rispetto a sh/bash, si potrebbe incorrere

in altri problemi. In tal caso aprite una segnalazione di errore a

<link xlink:href="&url.php.bugs;">&url.php.bugs;</link>.

Si può facilmente incorrere in problemi utilizzando variabili

(shell o PHP) nel codice command-line, o utilizzando le barre rovesciate (backslash) per

l'escape, quindi occorre essere molto prudenti. Siete avvertiti.

</para>

</note>

<note>

<para>

L'opzione <option>-r</option> è disponibile nella &cli.sapi; ma non

nella <emphasis>CGI</emphasis> <acronym>SAPI</acronym>.

</para>

</note>

<note>

<para>

Questa opzione è prevista solo per codice molto semplice, quindi alcune

direttive di configurazione (come <link

linkend="ini.auto-prepend-file">auto_prepend_file</link> e <link

linkend="ini.auto-append-file">auto_append_file</link>) sono ignorate

in questa modalità.

</para>

</note>

</entry>

</row>

<row>

<entry>-B</entry>

<entry>--process-begin</entry>

<entry>

<para>

Codice PHP da eseguire prima di processare stdin.

</para>

</entry>

</row>

<row>

<entry>-R</entry>

<entry>--process-code</entry>

<entry>

<para>

Esegue il codice PHP per ogni linea di input.

</para>

<para>

In questa modalità si hanno due variabili speciali:

<varname>$argn</varname> ed <varname>$argi</varname>.

<varname>$argn</varname> contiene la linea PHP in elaborazione al momento,

mentre <varname>$argi</varname> contiene il numero

di linea.

</para>

</entry>

</row>

<row>

<entry>-F</entry>

<entry>--process-file</entry>

<entry>

<para>

Esegue il file PHP per ogni linea di input.

</para>

</entry>

</row>

<row>

<entry>-E</entry>

<entry>--process-end</entry>

<entry>

<para>

Codice PHP da eseguirsi dopo il processamento dell'input.

</para>

<para><example>

<title>Utilizzo delle opzioni <option>-B</option>, <option>-R</option> e

<option>-E</option> per contare il numero di linea di un

progetto.

</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-S</entry>

<entry>--server</entry>

<entry>

<para>

Avvia il <link linkend="features.commandline.webserver">web server

interno</link>.

</para>

</entry>

</row>

<row>

<entry>-t</entry>

<entry>--docroot</entry>

<entry>

Specifica la document root per il <link

linkend="features.commandline.webserver">web server interno</link>.

</entry>

</row>

<row>

<entry>-s</entry>

<entry>--syntax-highlight e --syntax-highlighting</entry>

<entry>

<para>

Visualizza il sorgente con sintassi colorata.

</para>

<para>

Questa opzione utilizza il meccanismo interno di parsing dei file e produce

una versione HTML evidenziata del sorgente dirigendola verso lo

standard output. Occorre notare che questa funzione genera dei blocchi di tag HTML

<literal>&lt;code&gt; [...] &lt;/code&gt;</literal>

e non le intestazioni HTML.

</para>

<note>

<para>

Questa opzione non funziona abbinata all'opzione

<option>-r</option>.

</para>

</note>

</entry>

</row>

<row>

<entry>-v</entry>

<entry>--version</entry>

<entry>

<para><example>

<title>Utilizzo di <option>-v</option> per recuperare il nome <acronym>SAPI</acronym>

e la versione di PHP e Zend</title>

<screen>

</screen>

</example></para>

</entry>

</row>

<row>

<entry>-w</entry>

<entry>--strip</entry>

<entry>

<para>

Visualizza il sorgente senza gli spazi e i commenti.

</para>

<note>

<para>

Questa opzione non funziona abbinata all'opzione

<option>-r</option>.

</para>

</note>

</entry>

</row>

<row>

<entry>-z</entry>

<entry>--zend-extension</entry>

<entry>

<para>

Carica l'estensione Zend. Soltano se si fornisce un nome di file, il PHP tenta

di caricare l'estensione dal corrente percorso di default delle librerie

(solitamente, sui sistemi Linux, <filename>/etc/ld.so.conf</filename>).

Se si fornisce un nome di file con percorso assoluto, ls libreria non

sarà cercata nella directory di default. Un nome di file con percorso relativo

indica al PHP di tentare di caricare l'estensione con

percorso relativo alla directory corrente.

</para>

</entry>

</row>

<row>

<entry></entry>

<entry>--ini</entry>

<entry>

<para>

Visualizza i nomi dei file di configurazione e le cartelle scansionate.

<example>

<title>Esempio di uso di <literal>--ini</literal></title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--rf</entry>

<entry>--rfunction</entry>

<entry>

<para>

Visualizza le informazioni della funzione o metodo di classe indicato (es.

numero e nome dei parametri).

</para>

<para>

Questa opzione è disponibile solo se PH è stato compilato con il supporto alla

<link linkend="book.reflection">Reflection</link>.

</para>

<para>

<example>

<title>semplice utilizzo di <literal>--rf</literal></title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--rc</entry>

<entry>--rclass</entry>

<entry>

<para>

Visualizza le informazioni della classe indicata (lista delle costanti, proprietà

e metodi).

</para>

<para>

Questa opzione è disponibile solo se PH è stato compilato con il supporto alla

<link linkend="book.reflection">Reflection</link>.

</para>

<para>

<example>

<title>Esempio di <literal>--rc</literal></title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--re</entry>

<entry>--rextension</entry>

<entry>

<para>

Visualizza le informazioni dell'estensione indicata (elenco delle opzioni &php.ini;,

funzioni, costanti and classi definite).

</para>

<para>

Questa opzione è disponibile solo se PH è stato compilato con il supporto alla

<link linkend="book.reflection">Reflection</link>.

</para>

<para>

<example>

<title>Esempio di <literal>--re</literal></title>

<programlisting role="shell">

</programlisting>

</example>

</para>

</entry>

</row>

<row>

<entry>--rz</entry>

<entry>--rzendextension</entry>

<entry>

<para>

Visualizza le informazioni di configurazione per l'estensione Zend indicata (le

stesse informazioni che sono fornite da <function>phpinfo</function>).

</para>

</entry>

</row>

<row>

<entry>--ri</entry>

<entry>--rextinfo</entry>

<entry>

<para>

Visualizza le informazioni di configurazione per l'estensione indicata (le

stesse informazioni che sono fornite da <function>phpinfo</function>).

Le informazioni di configurazione del sistema di base

sono disponibili usando "main" come nome d'estensione.

</para>

<para>

<example>

<title><literal>--ri</literal> example</title>

<programlisting role="shell">