Chapitre 44. 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 .

Quel SAPI est installé ?: À partir d'un interpréteur de commande, 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 :

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 :

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 (prononcer "shebang ") 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 :

@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.