Utiliser PHP en ligne de commande

Depuis la version 4.3.0, PHP supporte un nouveau type de SAPI (Server Application Programming Interface, c'est-�-dire Interface de Programmation d'Applications Serveur) appel� CLI, ce qui signifie Command Line Interface et se traduit par "Interface de Ligne de Commande". Comme son nom l'indique, ce type SAPI cible les applications Shell (ou desktop), �crites en PHP. Il y a un certain nombre de diff�rences entre le type CLI SAPI et les autres SAPI expliqu�s dans ce chapitre. Il convient de pr�ciser que CLI et CGI sont des SAPI diff�rentes, bien qu'ils partagent des comportements similaires.

Le CLI SAPI a �t� publi� pour la premi�re fois avec la version PHP 4.2.0, mais il �tait exp�rimental, et devait �tre explicitement activ� avec l'option --enable-cli lorsque vous ex�cutez le script ./configure. Depuis PHP 4.3.0, le CLI SAPI n'est plus exp�rimental, et l'option --enable-cli est activ�e par d�faut. Vous pouvez utiliser l'option --disable-cli pour le d�sactiver.

Depuis PHP 4.3.0, le nom, l'emplacement et l'existence des binaires CLI/CGI vont d�pendre de la fa�on dont PHP est install� sur votre syst�me. Par d�faut, en ex�cutant make, les deux binaires CGI et CLI sont compil�s et nomm�s respectivement sapi/cgi/php et sapi/cli/php dans votre r�pertoire source PHP. Vous remarquerez que les deux se nomment php. Ce qui se passe ensuite pendant le make install d�pend de votre ligne de configuration. Si un module SAPI, apxs par exemple, a �t� choisi pendant la configuration, ou que l'option --disable-cgi a �t� activ�e, le CLI est copi� dans {PREFIX}/bin/php pendant le make install. Si, par exemple, --with--apxs figure dans votre ligne de configuration, le CLI est copi� dans {PREFIX}/bin/php pendant le make install, sinon c'est le CGI qui y est plac�. Si vous voulez forcer l'installation du binaire CGI, lancez make install-cli apr�s le make install. Sinon, vous pouvez aussi sp�cifier --disable-cgi dans votre ligne de configuration.

Note: Du fait que les deux options --enable-cli et --enable-cgi sont activ�es par d�faut, avoir simplement --enable-cli dans votre ligne de configuration n'implique pas n�cessairement que le CLI soit renomm� en {PREFIX}/bin/php pendant le make install.

Les paquets Windows entre PHP 4.2.0 et PHP 4.2.3 installaient le CLI en tant que php-cli.exe et laissaient le CGI en tant que php-cli.exe dans le m�me r�pertoire. Depuis PHP 4.3.0, le paquet Windows installe le CLI en tant que php.exe dans un r�pertoire � part nomm� cli, donc cli/php.exe. Depuis PHP 5, le CLI est install� dans le r�pertoire principal en tant que php.exe. La version CGI est nomm�e quand � elle php-cgi.exe.

Depuis PHP 5, un nouveau fichier php-win.exe est install�. C'est l'�quivalent de la version CLI � ceci pr�s qu'il n'affiche rien et ainsi ne fait pas appara�tre de console (aucune fen�tre "dos" n'appara�t � l'�cran). Ce comportement est similaire � celui de php-gtk. Vous pouvez l'activer avec l'option --enable-cli-win32.

Note: Quel SAPI est install� ?
� partir d'un terminal, lancer php -v vous dira si php est en version CGI ou CLI. Vous pouvez aussi consulter la fonction php_sapi_name() et la constante PHP_SAPI.

Note: Une page man de manuel Unix a �t� ajout�e avec PHP 4.3.2. Vous pouvez la consulter en tapant man php dans votre interpr�teur de commande.

Les diff�rences les plus notables entre le CLI SAPI et les SAPI sont :

• Contrairement au CGI SAPI, aucun en-t�te HTTP n'est �crit dans le r�sultat.

  Bien que le CGI SAPI fournisse un moyen de supprimer les en-t�tes HTTP, il n'y a pas moyen d'activer les en-t�tes HTTP dans le CLI SAPI.

  CLI est lanc� en mode silencieux par d�faut, bien que les options -q et --no-header soient gard�es pour rester compatible avec les anciennes versions CGI.

  Il ne change pas le r�pertoire courant en celui du script. (les options -C et --no-chdir sont gard�es par souci de compatibilit�)

  Messages d'erreurs en texte brut (pas de formatage HTML).

• Il y a plusieurs directives du php.ini qui sont ignor�es par le CLI SAPI, car elles n'ont pas de sens en environnement shell :

  Directives php.ini ignor�es

  Directive	Valeur par d�faut pour CLI SAPI	Commentaire
  html_errors	FALSE	Il peut �tre bien difficile de lire les messages d'erreur sur un terminal lorsqu'ils sont noy�s dans des balises HTML sans grand int�r�t. Par cons�quent, cette directive est forc�e � FALSE.
  implicit_flush	TRUE	Il est souhaitable que tout affichage en provenance de print(), echo() et consorts, soit imm�diatement affich� dans le terminal, et non pas plac� dans un buffer quelconque. Vous pouvez toujours utiliser la bufferisation de sortie si vous voulez retarder un affichage, ou bien en manipuler le contenu une derni�re fois.
  max_execution_time	0 (sans limite)	�tant donn�es les possibilit�s infinies de PHP en environnement shell, le temps d'ex�cution maximal d'un script PHP a �t� rendu illimit�. Alors que les scripts destin�s au web doivent s'accomplir en une fraction de seconde, il arrive que les scripts shell requi�rent bien plus de temps.
  register_argc_argv	TRUE	En donnant la valeur de TRUE � cette directive, vous aurez toujours acc�s � la variable argc (repr�sentant le nombre d'arguments pass�s � l'application) et argv (le tableau contenant les arguments pass�s) dans le CLI SAPI. Depuis PHP 4.3.0, les variables $argc et $argv sont d�finies et remplies avec les valeurs appropri�es, en utilisant CLI SAPI. Avant cette version, la cr�ation de ces variables �tait li�e au comportement des versions CGI et MODULE, qui requi�rent l'activation de la directive register_globals. Ind�pendamment de la version ou de la valeur de register_globals, vous pouvez toujours acc�der � $_SERVER et $HTTP_SERVER_VARS. Par exemple : $_SERVER['argv']

  Note: Ces directives ne peuvent pas �tre initialis�es avec d'autres valeurs dans le fichier php.ini ou par une autre m�thode. C'est une limitation, car ces valeurs par d�faut s'appliquent une fois que tous les autres fichiers de configuration ont �t� analys�s. Cependant, ces valeurs peuvent �tre modifi�es durant l'ex�cution (ce qui n'est pas logique pour certaines directives, comme register_argc_argv).
  

• Pour faciliter le travail en environnement shell, les constantes suivantes sont d�finies :

  Constantes sp�cifiques au CLI

  Constante	Description
  STDIN	Un pointeur de fichier d�j� disponible vers stdin. Cela �vite de l'ouvrir avec <?php $stdin = fopen('php://stdin', 'r'); ?> Si vous voulez lire une seule ligne depuis stdin, vous pouvez utiliser : <?php $line = trim(fgets(STDIN)); // lit une seule ligne depuis STDIN fscanf(STDIN, "%d\n", $number); // lit les nombres depuis STDIN ?>
  STDOUT	Un descripteur de fichier d�j� disponible vers stdout. Cela �vite de l'ouvrir avec <?php $stdout = fopen('php://stdout', 'w'); ?>
  STDERR	Un descripteur de fichier d�j� disponible vers stderr. Cela �vite de l'ouvrir avec <?php $stderr = fopen('php://stderr', 'w'); ?>

  �tant donn� ce qui pr�c�de, vous n'avez pas besoin d'ouvrir un flux vers stderr par vous-m�me, mais vous pouvez utiliser cette constante directement, comme un descripteur de fichier :

  php -r 'fwrite(STDERR, "stderr\n");'

  Vous n'avez pas non plus � fermer explicitement ces fichiers, PHP s'en chargera automatiquement � la fin du script.

  Note: Ces constantes ne sont pas disponibles si le script PHP est lu depuis stdin.
  

• Le CLI SAPI ne transforme pas le dossier courant en dossier d'ex�cution du script !

  Exemple montrant la diff�rence avec le CGI SAPI :

  <?php
// Un test simple : affiche le dossier d'ex�cution */
echo getcwd(), "\n";
?>

  Lorsque vous utilisez la version CGI, l'affichage sera :

  $ pwd
  /tmp
  
  $ php-cgi -f autre_dossier/test.php
  /tmp/autre_dossier
  

  Cela montre clairement que PHP modifie le dossier courant, et utilise le dossier du script ex�cut�.

  En utilisant le CLI SAPI, on obtient :

  $ pwd
  /tmp
  
  $ php -f autre_dossier/test.php
  /tmp
  

  Cela donne beaucoup plus de souplesse lorsque vous r�digez des scripts shell avec PHP.

  Note: Le CGI SAPI se comporte de la m�me fa�on que le CLI SAPI, en lui passant l'option -C, lorsque vous l'invoquez en ligne de commande.
  

La liste des options de ligne de commande fournies par PHP est disponible � n'importe quel moment en ex�cutant PHP avec l'option -h :

Usage: php [options] [-f] <file> [--] [args...]
 php [options] -r <code> [--] [args...]
 php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
 php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
 php [options] -- [args...]
 php [options] -a

-a               Run interactively
-c <path>|<file> Look for php.ini file in this directory
-n               No php.ini file will be used
-d foo[=bar]     Define INI entry foo with value 'bar'
-e               Generate extended information for debugger/profiler
-f <file>        Parse and execute <file>.
-h               This help
-i               PHP information
-l               Syntax check only (lint)
-m               Show compiled in modules
-r <code>        Run PHP <code> without using script tags <?..?>
-B <begin_code>  Run PHP <begin_code> before processing input lines
-R <code>        Run PHP <code> for every input line
-F <file>        Parse and execute <file> for every input line
-E <end_code>    Run PHP <end_code> after processing all input lines
-H               Hide any passed arguments from external tools.
-s               Display colour syntax highlighted source.
-v               Version number
-w               Display source with stripped comments and whitespace.
-z <file>        Load Zend extension <file>.

args...          Arguments passed to script. Use -- args when first argument
                 starts with - or script is read from stdin

--ini            Show configuration file names

--rf <name>      Show information about function <name>.
--rc <name>      Show information about class <name>.
--re <name>      Show information about extension <name>.
--ri <name>      Show configuration for extension <name>.

Le CLI SAPI dispose de trois moyens pour lire le code du script PHP que vous voulez ex�cuter :

1. Indiquer � PHP d'ex�cuter un fichier donn� :

   php mon_script.php
   
   php -f mon_script.php
   

   Les deux m�thodes (en utilisant -f ou pas) ex�cutent le script contenu dans le fichier mon_script.php. Vous pouvez choisir n'importe quel fichier, et ces fichiers ne sont pas tenus d'utiliser l'extension .php. N'importe quelle extension peut faire l'affaire.

   Note: Si vous devez passer des arguments � votre script, vous devez passer -- comme premier argument lorsque vous utilisez -f.
   

2. Donner du code PHP � ex�cuter directement en ligne de commande.

   php -r 'print_r(get_defined_constants());'
   

   Une attention particuli�re doit alors �tre apport�e aux variables d'environnement, qui seront remplac�es, et aux guillemets, qui ont des significations sp�ciales en ligne de commande.

   Note: Lisez l'exemple attentivement, il n'y a ni balise d'ouverture, ni balise de fermeture ! L'option -r rend caduque l'utilisation de celles-ci, et les ajouter conduirait alors � une erreur d'analyse syntaxique.
   

3. Alimenter l'entr�e standard en code PHP (stdin).

   Cela donne la possibilit� de cr�er dynamiquement du code PHP, puis de le fournir � PHP, et enfin, de le traiter � nouveau en shell. Voici un exemple fictif :

   $ some_application | some_filter | php | sort -u >final_output.txt
   

Il n'est pas possible de combiner ces trois modes d'ex�cution.

Comme toute application shell, l'ex�cutable PHP accepte des arguments, et votre script PHP peut aussi les recevoir. Le nombre d'arguments n'est pas limit� par PHP (le shell a une limite en terme de nombre de caract�res qui peuvent �tre pass�s. G�n�ralement, vous n'atteindrez pas cette limite). Les arguments pass�s au script seront transmis via la variable tableau $argv. L'index z�ro contiendra toujours le nom du script appel� (qui sera - dans le cas o� le code PHP arrive de l'entr�e standard ou depuis la ligne de commande, pass� -r). L'autre variable globale fournie est $argc qui contient le nombre d'�l�ments dans le tableau $argv (ce nombre est diff�rent du nombre d'arguments pass�s au script).

Tant que les arguments que vous passez � votre script ne commencent pas par le caract�re -, il n'y a rien de sp�cial � surveiller. Si vous passez des arguments � votre script qui commencent par -, cela posera des probl�mes car PHP va penser qu'il doit les interpr�ter. Pour �viter cela, utilisez le s�parateur --. Apr�s cet argument, tous les arguments suivants seront pass�s � votre script sans �tre modifi�s ou analys�s par PHP.

# Cela ne va pas ex�cuter le code, mais afficher l'aide de PHP
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# Cela va passer l'argument '-h' � votre script, et �viter que PHP ne le traite
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
}

Cependant, il y a une autre m�thode pour utiliser PHP en script shell. Vous pouvez aussi utiliser la ligne #!/usr/bin/php en tout d�but de votre script, suivie de code PHP compris entre balise ouvrantes/fermantes. Apr�s avoir mis les droits d'ex�cution sur votre script (chmod +x test), il peut �tre ex�cut� comme un script shell ou perl habituel :

$ chmod +x test
$ ./test -h -- foo
array(4) {
   [0]=>
   string(6) "./test"
   [1]=>
   string(2) "-h"
   [2]=>
   string(2) "--"
   [3]=>
   string(3) "foo"
}

Comme vous le voyez, aucune pr�caution n'est n�cessaire pour passer des param�tres qui commencent par - � votre script.

Les options longues sont disponibles depuis PHP 4.3.3.

$ php -c /custom/directory/ mon_script.php

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

 -d configuration_directive[=value]

# L'omission de la valeur conduit � donner la valeur de "1"
$ php -d max_execution_time -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Passer une valeur vide conduit � donner la valeur de ""
php -d max_execution_time= -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# La directive de configuration sera n'importe quelle valeur pass�e apr�s le caract�re '='
$  php -d max_execution_time=20 -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php -d max_execution_time=doesntmakesense -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328

$ php -v
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies

$ php --ini
Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
Scan for additional .ini files in: (none)
Additional .ini files parsed:      (none)

$ php --rf var_dump
Function [ <internal> public function var_dump ] {

- Parameters [2] {
Parameter #0 [ <required> $var ]
Parameter #1 [ <optional> $... ]
}
}

$ php --rc Directory
Class [ <internal:standard> class Directory ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [0] {
  }

  - Methods [3] {
    Method [ <internal> public method close ] {
    }

    Method [ <internal> public method rewind ] {
    }

    Method [ <internal> public method read ] {
    }
  }
}

$ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {

  - Functions {
    Function [ <internal> function json_encode ] {
    }
    Function [ <internal> function json_decode ] {
    }
  }
}

$ php --ri date

date

date/time support => enabled
"Olson" Timezone Database Version => 2007.5
Timezone Database => internal
Default timezone => Europe/Oslo

Directive => Local Value => Master Value
date.timezone => Europe/Oslo => Europe/Oslo
date.default_latitude => 59.22482 => 59.22482
date.default_longitude => 11.018084 => 11.018084
date.sunset_zenith => 90.583333 => 90.583333
date.sunrise_zenith => 90.583333 => 90.583333

L'ex�cutable PHP peut �tre utilis� pour ex�cuter des scripts ind�pendants du serveur web. Si vous �tes sur un syst�me Unix, il est recommand� d'ajouter la ligne sp�ciale en d�but de script, de le rendre ex�cutable de mani�re � ce que le syst�me sache quel programme doit ex�cuter le script. Sous Windows, vous pouvez associer l'ex�cutable php.exe avec le double-clic sur les fichiers d'extension .php, ou bien vous pouvez faire un fichier batch pour ex�cuter le script gr�ce � PHP. La premi�re ligne utilis�e dans le monde Unix ne perturbera pas l'ex�cution sous Windows, ce qui rend les scripts facilement portables. Un exemple complet est disponible ci-dessous :

Dans le script ci-dessus, nous utilisons la premi�re ligne pour indiquer que le fichier doit �tre ex�cut� par PHP. Nous travaillons avec une version CLI, donc aucun en-t�te HTTP n'est affich�. Il y a deux variables que vous pouvez utiliser avec les applications de ligne de commande : $argc et $argv. La premi�re est le nombre d'arguments plus un (le nom du script qui est ex�cut�). La seconde est un tableau contenant les arguments, commen�ant avec le nom du script en �l�ment 0 ($argv[0]).

Dans notre exemple, nous avons v�rifi� qu'il y a plus ou moins d'un argument. De plus, si cet argument est --help, -help, -h ou -?, nous affichons un message d'aide, ainsi que le nom du script. Si nous recevons un autre argument, celui-ci est affich� dans le terminal.

Pour ex�cuter le script ci-dessus sous Unix, vous devez le rendre ex�cutable, puis l'appeler avec une commande comme : script.php echothis ou script.php -h. Sous Windows, vous pouvez faire un fichier batch pour cela :

@echo OFF
"C:\php\php.exe" script.php %*

Si vous avez nomm� le programme ci-dessus script.php, et que vous avez votre ex�cutable php.exe situ� � C:\php\php.exe, ce fichier batch l'ex�cutera avec les options que vous lui passez : script.bat echothis ou script.bat -h.

Voir aussi l'extension Readline, qui dispose de nombreuses fonctions pour am�liorer la convivialit� de vos applications en ligne de commande.