Chapitre 23. Utiliser PHP en ligne de commande

Depuis la version 4.3, 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 pas mal de différences enter le type CLI SAPI et les autres SAPI, qui sont expliqués dans ce chapitre.

Le CLI SAPI a été publié pour la première fois avec la version PHP 4.2.0, mais il est resté expérimental, et doit être explicitement activé avec la commande --enable-cli, lorsque vous exécutez le script ./configure. Depuis PHP 4.3.0, le CLI SAPI n'est plus expérimental, et est donc toujours compilé et installé comme binaire PHP (appelé aussi php.exe sous Windows).

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.

• 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 :

  Tableau 23-1. 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êts. 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 ultimement le contenu.
  max_execution_time	0 (unlimited)	Etant donné 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 PHP register_globals. Indépendamment de la version ou de la valeur de register_globals, vous pouvez toujour 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 par exemple register_argc_argv).

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

  Tableau 23-2. Constantes spécifiques au CLI

  Constante	Déscription
  STDIN	Un descripteur de fichier déjà disponible vers stdin. Cela évite de l'ouvrir avec $stdin = fopen('php://stdin', 'r');
  STDOUT	Un descripteur de fichier déjà disponible vers stdout. Cela évite de l'ouvrir avec $stdout = fopen('php://stdout', 'w');
  STDERR	Un descripteur de fichier déjà disponible vers stderr. Cela évite de l'ouvrir avec $stderr = fopen('php://stderr', 'w');

  Etant donné ce qui précède, vous n'avez pas besoin d'ouvrir un fichier 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.

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

  Exemple de différence entre CGI SAPI et CLI SAPI:

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

  Lorsque vous utilisez la version CGI, l'affichage pourra être

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

  Cela monter 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 : CGI SAPI supporte le même comportement de CLI SAPI, en lui passant l'option -C, lorsque vous l'invoquez en ligne de commmande.

La liste des options de ligne de commande fournies par PHP est disponible en exécutant PHP avec l'option -h :

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

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 :

   php mon_script.php php -f mon_script.php

   Les deux méthodes (en utilisant -f ou pas) exécute 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.

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 guillements, 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 fonctionne sans ces balises, et les ajouter conduira alors à une erreur d'analyse.

3. Donner du code PHP dans l'entrée standard (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

Comme toute application shell, l'exécutable PHP accepte des arguments, et votre script peut aussi les recevoirs. Le nombre d'arguments n'est pas limité par PHP, mais par le shell, qui a une limite en terme de nombre de caractères qui peuvent être passés. Généralement, vous n'atteidrez pas cette limite, mais cela reste possible. Les arguments passés au script seront transmis via la variable tableau $argv. L,index zéro contiendra toujours le nom du script appelé. Si le code a été fourni en ligne de commande, ou via stdin, ce premier élément vaudra -. 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 à voter 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é ou analysé 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' &agrave; votre script, et &eacute;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, suivi de code PHP compris entre balise ouvrantes/fermantes. Vous pouvez aussi ajouter après #!/usr/bin/php les options nécessaires. Vous pouvez aussi le faire en ligne de commande. De cette manière, le script peut être exécuté comme un script shell habituel :

#!/usr/bin/php <?php     var_dump($argv); ?>

En supposant que ce fichier s'appelletest, dans le dossier courant, nous pouvons alors faire ceci :

$ chmod 755 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.

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 de configuration en début de scripts, 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 PHP sous Windows, ce qui rend les scripts facilements 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 il n'y a pas d'en-têtes HTTP qui soient affichés. 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 avons affiché un message d'aide, ainsi que le nom du script. Nous nous recevons un autre argument, cet argument est affiché dans le terminal.

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

@c:\php\php.exe script.php %1 %2 %3 %4

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.