admin/doc-fr
1
0
Fork 0
mirror of https://github.com/macintoshplus/doc-fr.git synced 2026-03-24 08:52:09 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
doc-fr/features/commandline.xml
David CARLIER d04b7407be features sync with EN (#1531)
2024-10-03 04:23:40 +01:00

2027 lines
64 KiB
XML
Executable File
Raw Permalink Blame History

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 725ceadea94af4f4db6c76b9665829f27068d2c5 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="features.commandline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Utiliser PHP en ligne de commande</title>
<titleabbrev>Utilisation des lignes de commande</titleabbrev>
<!--Introduction: {{{-->
<section xml:id="features.commandline.introduction" annotations="chunk:false">
<title>Introduction</title>
<para>
Le but premier de &cli.sapi; est le développement
d'applications shell avec PHP. Les différences entre le &cli.sapi;
et les autres <acronym>SAPI</acronym> sont
expliqués dans ce chapitre. Il est important de mentionner que &cli;
et <acronym>CGI</acronym> sont des <acronym>SAPI</acronym> différents malgré
le fait qu'ils puissent partager la majeure partie de leurs comportements.
</para>
<para>
Le &cli.sapi; est activé par défaut en utilisant l'option
<option role="configure">--enable-cli</option>, mais vous pouvez le désactiver
en utilisant l'option <option role="configure">--disable-cli</option>
lors de l'exécution de la commande <command>./configure</command>.
</para>
<para>
Le nom, l'emplacement et l'existence des binaires &cli;/<acronym>CGI</acronym>
vont dépendre de la façon dont PHP est installé sur votre système. Par
défaut, en exécutant <command>make</command>, les deux binaires <acronym>CGI</acronym>
et &cli; sont compilés et nommés respectivement <filename>sapi/cgi/php</filename> et
<filename>sapi/cli/php</filename> dans votre répertoire source PHP. Vous
remarquerez que les deux se nomment <filename>php</filename>. Ce qui se passe
ensuite pendant le <command>make install</command> dépend de votre ligne
de configuration. Si un module <acronym>SAPI</acronym>, apxs par exemple, a été choisi pendant la
configuration, ou que l'option <option role="configure"> --disable-cgi</option> a été
activée, le &cli; est copié dans <filename>{PREFIX}/bin/php</filename> pendant
le <command>make install</command> sinon, le <acronym>CGI</acronym> sera placé ici.
Si, par exemple, <option role="configure">--with-apxs</option> figure dans votre
ligne de configuration, le &cli; est copié dans <filename>{PREFIX}/bin/php</filename>
pendant le <command>make install</command>. Si vous voulez forcer l'installation du
binaire <acronym>CGI</acronym>, lancez <command>make install-cli</command>
après le <command>make install</command>. Sinon, vous pouvez aussi spécifier
<option role="configure">--disable-cgi</option> dans votre ligne de configuration.
</para>
<note>
<para>
Du fait que les deux options <option role="configure">--enable-cli</option> et
<option role="configure">--enable-cgi</option> sont activées par défaut, avoir simplement
<option role="configure">--enable-cli</option> dans votre ligne de configuration
n'implique pas nécessairement que le CLI soit renommé en <filename>
{PREFIX}/bin/php</filename> pendant le <command>make install</command>.
</para>
</note>
<para>
Le binaire &cli; est distribué dans le dossier principal
sous le nom de <filename>php.exe</filename> sous Windows. La version
<acronym>CGI</acronym> est distribuée sous le nom de <filename>php-cgi.exe</filename>.
De plus, un fichier <filename>php-win.exe</filename> est distribué si PHP
est configuré en utilisant l'option de configuration
<option role="configure">--enable-cli-win32</option>. Ce fichier fait la
même chose que la version &cli;, sauf qu'il n'affiche rien et qu'il ne fournit
pas de console.
</para>
<note>
<title>Quel SAPI est installé ?</title>
<para>
À partir d'un terminal, lancer <command>php -v</command> vous dira si
<filename>php</filename> est en version <acronym>CGI</acronym> ou
&cli;. Vous pouvez aussi consulter la fonction
<function>php_sapi_name</function> et la constante
<constant>PHP_SAPI</constant>.
</para>
</note>
<note>
<para>
Une page <literal>man</literal> de manuel Unix est disponible
en tapant <command>man php</command> dans l'interpréteur de commande.
</para>
</note>
</section>
<!--}}}-->
<!--Differences: {{{-->
<section xml:id="features.commandline.differences">
<title>Différence avec les autres <acronym>SAPI</acronym>s</title>
<para>
Les différences les plus notables entre le &cli; <acronym>SAPI</acronym> et les
<acronym>SAPI</acronym> sont :
<itemizedlist>
<listitem>
<para>
Contrairement au <acronym>CGI</acronym> <acronym>SAPI</acronym>, aucun
en-tête HTTP n'est écrit dans le résultat.
</para>
<para>
Bien que le <acronym>CGI</acronym> <acronym>SAPI</acronym> fournisse un
moyen de supprimer les en-têtes HTTP, il n'est pas possible d'activer les
en-têtes HTTP dans le &cli.sapi;.
</para>
<para>
&cli; est lancé en mode silencieux par défaut, bien que les options
<option>-q</option> et <option>--no-header</option> soient gardées
pour rester compatible avec les anciennes versions <acronym>CGI</acronym>.
</para>
<para>
Il ne change pas le répertoire courant en celui du script.
(les options <option>-C</option> et <option>--no-chdir</option> sont
gardées par souci de compatibilité)
</para>
<para>
Messages d'erreurs en texte brut (pas de formatage <acronym>HTML</acronym>).
</para>
</listitem>
<listitem>
<para>
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 :
</para>
<para>
<table>
<title>Directives &php.ini; ignorées</title>
<tgroup cols="3">
<thead>
<row>
<entry>Directive</entry>
<entry>Valeur par défaut pour &cli; <acronym>SAPI</acronym></entry>
<entry>Commentaire</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend="ini.html-errors"><option>html_errors</option></link></entry>
<entry>&false;</entry>
<entry>
Par défaut à &false;, vu qu'il peut être bien difficile de lire des messages
d'erreur sur un terminal lorsqu'ils sont noyés dans des balises <acronym>HTML</acronym>
non-interprétées.
</entry>
</row>
<row>
<entry><link linkend="ini.implicit-flush"><option>implicit_flush</option></link></entry>
<entry>&true;</entry>
<entry>
Dans un terminal, il est généralement souhaitable que tout affichage en provenance de
<function>print</function>,
<function>echo</function>
et autres, soit immédiatement affiché, et non pas placé dans un
buffer quelconque. Néanmoins, il est toujours possible d'utiliser
<link linkend="ref.outcontrol">la bufferisation de sortie</link>
si vous voulez retarder un affichage, ou bien en manipuler le contenu
une dernière fois.
</entry>
</row>
<row>
<entry><link linkend="ini.max-execution-time">max_execution_time</link></entry>
<entry>0 (sans limite)</entry>
<entry>
PHP dans un terminal est susceptible d'être utilisé pour des tâches
bien plus diverses que dans des scripts web, et vu que cela
prend généralement beaucoup de temps, ce paramètre sera défini par défaut
à 0 permettant ainsi d'être illimité.
</entry>
</row>
<row>
<entry><link linkend="ini.register-argc-argv">register_argc_argv</link></entry>
<entry>&true;</entry>
<entry>
<para>
La définition à &true; de cette directive signifie que les scripts
exécutés via le <acronym>SAPI</acronym> &cli; auront toujours
accès à <emphasis>argc</emphasis> (représentant le nombre
d'arguments passés à l'application) et
<emphasis>argv</emphasis> (le tableau contenant les arguments passés).
</para>
<para>
Les variables PHP <varname>$argc</varname>
et <varname>$argv</varname> sont automatiquement définies et remplies
avec les valeurs appropriées, lors de l'utilisation du
<acronym>SAPI</acronym> &cli;. Ces valeurs peuvent également
être trouvées dans la variable <varname>$_SERVER</varname>, par exemple :
<varname>$_SERVER['argv']</varname>.
</para>
</entry>
</row>
<row>
<entry><link linkend="ini.output-buffering">output_buffering</link></entry>
<entry>&false;</entry>
<entry>
<para>
Même si cette configuration INI est codée en dur à &false;,
les fonctions relatives à
<link linkend="book.outcontrol">l'affichage du buffer</link>
sont disponibles.
</para>
</entry>
</row>
<row>
<entry><link linkend="ini.max-input-time">max_input_time</link></entry>
<entry>&false;</entry>
<entry>
<para>
Le PHP &cli; ne supporte pas GET, POST et le téléchargement de fichiers.
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<para>
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
<link linkend="ini.register-argc-argv">register_argc_argv</link>).
</para>
</note>
<note>
<para>
Il est recommandé de définir
<link linkend="ini.ignore-user-abort">ignore_user_abort</link> pour
les scripts en ligne de commande. Voir la fonction
<function>ignore_user_abort</function> pour plus d'informations.
</para>
</note>
</listitem>
<listitem>
<para>
Pour faciliter le travail en environnement shell, plusieurs constantes
sont définies pour les <link linkend="features.commandline.io-streams">flux
I/O</link>.
</para>
</listitem>
<listitem>
<para>
Le &cli.sapi; <emphasis role="strong">ne transforme pas</emphasis>
le dossier courant en dossier d'exécution du script.
</para>
<example>
<title>
Exemple montrant la différence avec le <acronym>SAPI</acronym>
<acronym>CGI</acronym> :
</title>
<programlisting role="php">
<![CDATA[
<?php
// Un test simple : affiche le dossier d'exécution */
echo getcwd(), "\n";
?>
]]>
</programlisting>
<para>
Lorsque vous utilisez la version <acronym>CGI</acronym>, l'affichage sera :
</para>
<screen>
<![CDATA[
$ pwd
/tmp
$ php -q autre_dossier/test.php
/tmp/autre_dossier
]]>
</screen>
<para>
Cela montre clairement que PHP modifie le dossier
courant, et utilise le dossier du script exécuté.
</para>
<para>
En utilisant le &cli.sapi;, on obtient :
</para>
<screen>
<![CDATA[
$ pwd
/tmp
$ php -f autre_dossier/test.php
/tmp
]]>
</screen>
<para>
Cela donne beaucoup plus de souplesse lorsque vous rédigez des
scripts shell avec PHP.
</para>
</example>
<note>
<para>
Le <acronym>CGI</acronym> <acronym>SAPI</acronym> se comporte de la même façon que le
&cli.sapi;, en lui passant l'option
<option>-C</option>, lorsque vous l'invoquez en ligne de commande.
</para>
</note>
</listitem>
</itemizedlist>
</para>
</section>
<!--}}}-->
<!--Options: {{{-->
<section xml:id="features.commandline.options">
<title>Options de ligne de commande</title>
<titleabbrev>Options</titleabbrev>
<para>
La liste des options de ligne de commande fournies par PHP
est disponible à n'importe quel moment en exécutant PHP avec l'option
<option>-h</option> :
<screen>
<![CDATA[
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 <addr>:<port> Run with built-in web server.
-t <docroot> Specify document root <docroot> for built-in web server.
-s Output HTML syntax highlighted source.
-v Version number
-w Output 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>.
--rz <name> Show information about Zend extension <name>.
--ri <name> Show configuration for extension <name>.
]]>
</screen>
</para>
<para>
<table>
<title>Options de ligne de commande</title>
<tgroup cols="2">
<thead>
<row>
<entry>Option</entry>
<entry>Option longue</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>-a</entry>
<entry>--interactive</entry>
<entry>
<para>
Lance PHP de façon interactive. Pour plus d'informations, reportez-vous
à la documentation concernant le <link
linkend="features.commandline.interactive">shell intéractif</link>.
</para>
</entry>
</row>
<row>
<entry>-b</entry>
<entry>--bindpath</entry>
<entry>
<para>
Lie le chemin pour les externes, en mode serveur FASTCGI
(<acronym>CGI</acronym> uniquement).
</para>
</entry>
</row>
<row>
<entry>-C</entry>
<entry>--no-chdir</entry>
<entry>
<para>
Ne pas aller dans le dossier du script (<acronym>CGI</acronym> uniquement).
</para>
</entry>
</row>
<row>
<entry>-q</entry>
<entry>--no-header</entry>
<entry>
<para>
Mode silencieux. Supprime la sortie des en-têtes <acronym>HTTP</acronym>
(<acronym>CGI</acronym> uniquement).
</para>
</entry>
</row>
<row>
<entry>-T</entry>
<entry>--timing</entry>
<entry>
<para>
Mesure le temps d'exécution du script, répété <varname>count</varname>
fois (<acronym>CGI</acronym> uniquement).
</para>
</entry>
</row>
<row>
<entry>-c</entry>
<entry>--php-ini</entry>
<entry>
<para>
Spécifie le nom du dossier dans lequel se trouve le fichier &php.ini;,
ou encore spécifie un fichier de configuration (<literal>INI</literal>)
directement (qui ne s'appelle pas obligatoirement &php.ini;) :
</para>
<para>
<informalexample>
<screen>
<![CDATA[
$ php -c /custom/directory/ mon_script.php
$ php -c /custom/directory/custom-file.ini mon_script.php
]]>
</screen>
</informalexample>
</para>
<para>
Si cette option n'est pas spécifiée, &php.ini; est recherché dans
les <link linkend="configuration.file">endroits par défaut</link>.
</para>
</entry>
</row>
<row>
<entry>-n</entry>
<entry>--no-php-ini</entry>
<entry>
<para>
Ignore totalement &php.ini;.
</para>
</entry>
</row>
<row>
<entry>-d</entry>
<entry>--define</entry>
<entry>
<para>
Définit une valeur personnalisée pour n'importe quelle directive
de configuration du fichier &php.ini;. La syntaxe est :
<screen>
<![CDATA[
-d configuration_directive[=value]
]]>
</screen>
</para>
<para>
<example>
<title>Example of using <literal>-d</literal> to set an INI setting</title>
<screen>
<![CDATA[
# 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"
]]>
</screen>
</example>
</para>
</entry>
</row>
<row>
<entry>-e</entry>
<entry>--profile-info</entry>
<entry>
<para>
Génère des informations étendues pour le profilage et le débogage.
</para>
</entry>
</row>
<row>
<entry>-f</entry>
<entry>--file</entry>
<entry>
<para>
Analyse et exécute le fichier spécifié. L'option <option>-f</option>
est facultative, et peut être omise. Le seul nom du fichier
est suffisant.
</para>
</entry>
</row>
<row>
<entry>-h et -?</entry>
<entry>--help et --usage</entry>
<entry>
Affiche des informations sur la liste courante des options de la
ligne de commande, ainsi que leur description.
</entry>
</row>
<row>
<entry>-i</entry>
<entry>--info</entry>
<entry>
Appelle la fonction <function>phpinfo</function>, et
affiche le résultat. Si PHP ne fonctionne pas
correctement, il est recommandé d'utiliser la commande <command>php -i</command>
et de voir s'il n'y a pas d'erreurs affichées avant ou après la
table d'information. N'oubliez pas que le résultat de cette
option, si vous utilisez le mode <acronym>CGI</acronym>, est au format
<acronym>HTML</acronym>, et donc de taille conséquente.
</entry>
</row>
<row>
<entry>-l</entry>
<entry>--syntax-check</entry>
<entry>
<para>
Vérifie la syntaxe mais n'exécute pas le code PHP donné.
L'entrée provenant de l'entrée standard sera traitée si aucun nom de fichier n'est spécifié,
sinon chaque fichier spécifié sera vérifié.
En cas de réussite, le message
<literal>No syntax errors detected in &lt;filename&gt;</literal>
(Littéralement, aucune erreur de syntaxe n'a été détectée dans le fichier)
est affiché sur la sortie standard.
En cas d'erreur, le message <literal>Errors parsing &lt;filename&gt;</literal>
(Littéralement, erreur d'analyse dans le fichier filename)
est affiché, en plus des messages d'erreurs détectés par l'analyseur
lui-même.
Si des erreurs sont trouvées dans les fichiers spécifiés (ou l'entrée standard),
le code de retour du shell est défini à <literal>-1</literal>, sinon le
code de retour du shell est défini à <literal>0</literal>.
</para>
<para>
Cette option ne détecte pas les erreurs fatales (par exemple les
fonctions non définies) qui nécessitent l'exécution du code.
</para>
<note>
<para>
Avant PHP 8.3.0, il n'était possible de spécifier qu'un seul nom de fichier
à vérifier.
</para>
</note>
<note>
<para>
Cette option ne fonctionne pas avec l'option <option>-r</option>.
</para>
</note>
</entry>
</row>
<row>
<entry>-m</entry>
<entry>--modules</entry>
<entry>
<para>
<example>
<title>Affichage des modules internes (et chargés) de PHP et Zend</title>
<screen>
<![CDATA[
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype
[Zend Modules]
]]>
</screen>
</example>
</para>
</entry>
</row>
<row>
<entry>-r</entry>
<entry>--run</entry>
<entry>
<para>
Permet l'exécution de PHP directement dans la ligne de commande.
Les balises de PHP (<literal>&lt;?php</literal> et <literal>?&gt;</literal>)
<emphasis role="strong">ne sont pas</emphasis> nécessaires, et causeront
une erreur d'analyse si elles sont présentes.
</para>
<note>
<para>
Une attention toute particulière doit être portée lors de l'utilisation de cette option
de PHP, pour qu'il n'y ait pas de collision avec
les substitutions de variables en ligne de commande, réalisées par le
shell.
</para>
<example>
<title>Erreur de syntaxe lors de l'utilisation de doubles guillemets</title>
<screen>
<![CDATA[
$ php -r "$foo = get_defined_constants();"
PHP Parse error: syntax error, unexpected '=' in Command line code on line 1
Parse error: syntax error, unexpected '=' in Command line code on line 1
]]>
</screen>
</example>
<para>
Le problème ici est que le shell (sh/bash) effectue une substitution
de variables, même avec les guillemets doubles <literal>"</literal>.
Puisque la variable <varname>$foo</varname> n'est probablement pas
définie dans le shell, elle est remplacée par rien, ce qui fait
que le code passé à PHP pour l'exécution est :
</para>
<informalexample>
<screen>
<![CDATA[
$ php -r " = get_defined_constants();"
]]>
</screen>
</informalexample>
<para>
La solution de ce problème est d'utiliser les guillemets simples
<literal>'</literal>. Les variables de ces chaînes ne seront pas
substituées par leurs valeurs par le shell.
</para>
<example>
<title>Utilisation de guillemets simples pour éviter une substitution
par le shell</title>
<screen>
<![CDATA[
$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
["E_ERROR"]=>
int(1)
["E_WARNING"]=>
int(2)
["E_PARSE"]=>
int(4)
["E_NOTICE"]=>
int(8)
["E_CORE_ERROR"]=>
[...]
]]>
</screen>
</example>
<para>
Si un shell différent de sh/bash est utilisé, d'autres problèmes pourront
être rencontrés - si approprié, un rapport de bogues pourra être ouvert via
à <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>.
Il est toujours très facile d'avoir des problèmes lorsque vous essayez
d'inclure des variables shell dans le code, ou d'utiliser les antislashs
pour la protection. Vous aurez été prévenu !
</para>
</note>
<note>
<para>
<option>-r</option> est disponible avec le &cli.sapi;
mais pas avec le <acronym>SAPI</acronym> <emphasis>CGI</emphasis>.
</para>
</note>
<note>
<para>
Cette option est seulement utilisée pour des choses simples. Ainsi,
quelques directives de configuration (par exemple <link
linkend="ini.auto-prepend-file">auto_prepend_file</link> et <link
linkend="ini.auto-append-file">auto_append_file</link>) sont ignorées
dans ce mode.
</para>
</note>
</entry>
</row>
<row>
<entry>-B</entry>
<entry>--process-begin</entry>
<entry>
<para>
Code PHP à exécuter avant le traitement de stdin.
</para>
</entry>
</row>
<row>
<entry>-R</entry>
<entry>--process-code</entry>
<entry>
<para>
Code PHP à exécuter pour chaque ligne en entrée.
</para>
<para>
Il y a deux variables spéciales de disponibles dans ce mode :
<varname>$argn</varname> et <varname>$argi</varname>.
<varname>$argn</varname> doit contenir la ligne PHP
traitée à ce moment donné, tandis que
<varname>$argi</varname> doit contenir le numéro de la ligne.
</para>
</entry>
</row>
<row>
<entry>-F</entry>
<entry>--process-file</entry>
<entry>
<para>
Fichier PHP à exécuter pour chaque ligne en entrée.
</para>
</entry>
</row>
<row>
<entry>-E</entry>
<entry>--process-end</entry>
<entry>
<para>
Code PHP à exécuter après avoir effectué l'entrée.
</para>
<para>
<example>
<title>Exemple d'utilisation des options <option>-B</option>, <option>-R</option>
et <option>-E</option> pour compter le nombre de lignes d'un projet.
</title>
<screen>
<![CDATA[
$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328
]]>
</screen>
</example>
</para>
</entry>
</row>
<row>
<entry>-S</entry>
<entry>--server</entry>
<entry>
<para>
Démarre le <link linkend="features.commandline.webserver">serveur
web interne</link>. Disponible depuis 5.4.0.
</para>
</entry>
</row>
<row>
<entry>-t</entry>
<entry>--docroot</entry>
<entry>
Spécifie la racine des documents pour le <link
linkend="features.commandline.webserver">serveur web interne</link>.
</entry>
</row>
<row>
<entry>-s</entry>
<entry>--syntax-highlight et --syntax-highlighting</entry>
<entry>
<para>
Affiche le code avec la colorisation syntaxique.
</para>
<para>
Cette option utilise le mécanisme interne pour analyser le fichier,
et écrire au format HTML une version colorisée du code source.
Notez que cette option ne fait que générer un bloc HTML, avec les balises HTML
<literal>&lt;code&gt; [...] &lt;/code&gt;</literal>, sans en-têtes HTML.
</para>
<note>
<para>
Cette option ne fonctionne pas avec l'option <option>-r</option>.
</para>
</note>
</entry>
</row>
<row>
<entry>-v</entry>
<entry>--version</entry>
<entry>
<para><example>
<title>Utilisation de l'option <option>-v</option> pour récupérer le nom du <acronym>SAPI</acronym>
ainsi que la version de PHP et de Zend</title>
<screen>
<![CDATA[
$ php -v
PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
]]>
</screen>
</example>
</para>
</entry>
</row>
<row>
<entry>-w</entry>
<entry>--strip</entry>
<entry>
<para>
Affiche la source sans les commentaires ni les espaces.
</para>
<note>
<para>
Cette option ne fonctionne pas avec l'option <option>-r</option>.
</para>
</note>
</entry>
</row>
<row>
<entry>-z</entry>
<entry>--zend-extension</entry>
<entry>
<para>
Charge une extension Zend. Si et seulement si un fichier est fourni, PHP
essaie de charger cette extension dans le dossier courant par défaut
des bibliothèques sur votre système (généralement spécifié avec
<filename>/etc/ld.so.conf</filename> sous Linux par exemple). Passer un nom de
fichier avec le chemin complet fera que PHP utilisera ce fichier,
sans recherche dans les dossiers classiques. Un chemin de dossier
relatif, incluant les informations sur le dossier, indiquera à PHP qu'il doit
chercher les extensions uniquement dans ce dossier.
</para>
</entry>
</row>
<row>
<entry></entry>
<entry>--ini</entry>
<entry>
<para>
Affiche les noms des fichiers de configuration et des dossiers analysés.
<example>
<title>Exemple avec <literal>--ini</literal></title>
<programlisting role="shell">
<![CDATA[
$ 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)
]]>
</programlisting>
</example>
</para>
</entry>
</row>
<row>
<entry>--rf</entry>
<entry>--rfunction</entry>
<entry>
<para>
Affiche des informations sur la fonction donnée ou la méthode
d'une classe (i.e. nombre et nom des paramètres).
</para>
<para>
Cette option n'est disponible que si PHP a été compilé avec le support
<link linkend="book.reflection">Reflection</link>.
</para>
<para>
<example>
<title>Exemple avec <literal>--rf</literal></title>
<programlisting role="shell">
<![CDATA[
$ php --rf var_dump
Function [ <internal> public function var_dump ] {
- Parameters [2] {
Parameter #0 [ <required> $var ]
Parameter #1 [ <optional> $... ]
}
}
]]>
</programlisting>
</example>
</para>
</entry>
</row>
<row>
<entry>--rc</entry>
<entry>--rclass</entry>
<entry>
<para>
Affiche des informations sur la classe donnée (liste des constantes,
propriétés et méthodes).
</para>
<para>
Cette option n'est disponible que si PHP a été compilé avec le support
<link linkend="book.reflection">Reflection</link>.
</para>
<para>
<example>
<title>Exemple avec <literal>--rc</literal></title>
<programlisting role="shell">
<![CDATA[
$ 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 ] {
}
}
}
]]>
</programlisting>
</example>
</para>
</entry>
</row>
<row>
<entry>--re</entry>
<entry>--rextension</entry>
<entry>
<para>
Affiche les informations sur l'extension donnée (liste les options du
&php.ini;, les fonctions définies, les constantes et les classes).
</para>
<para>
Cette option n'est disponible que si PHP a été compilé avec le support
<link linkend="book.reflection">Reflection</link>.
</para>
<para>
<example>
<title>Exemple avec <literal>--re</literal></title>
<programlisting role="shell">
<![CDATA[
$ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {
- Functions {
Function [ <internal> function json_encode ] {
}
Function [ <internal> function json_decode ] {
}
}
}
]]>
</programlisting>
</example>
</para>
</entry>
</row>
<row>
<entry>--rz</entry>
<entry>--rzendextension</entry>
<entry>
<para>
Affiche les informations de configuration pour l'extension Zend fourni
(les mêmes informations que celles retournées par la fonction
<function>phpinfo</function>).
</para>
</entry>
</row>
<row>
<entry>--ri</entry>
<entry>--rextinfo</entry>
<entry>
<para>
Affiche les informations de configuration pour l'extension donnée (les
mêmes informations retournées par la fonction <function>phpinfo</function>).
Les informations de configurations internes
sont disponibles en utilisant le nom d'extension "main" ou "core".
</para>
<para>
<example>
<title>Exemple avec <literal>--ri</literal></title>
<programlisting role="shell">
<![CDATA[
$ php --ri date
date
date/time support => enabled
"Olson" Timezone Database Version => 2009.20
Timezone Database => internal
Default timezone => Europe/Oslo
Directive => Local Value => Master Value
date.timezone => Europe/Oslo => Europe/Oslo
date.default_latitude => 59.930972 => 59.930972
date.default_longitude => 10.776699 => 10.776699
date.sunset_zenith => 90.583333 => 90.583333
date.sunrise_zenith => 90.583333 => 90.583333
]]>
</programlisting>
</example>
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<para>
Les options <literal>-rBRFEH</literal>, <literal>--ini</literal> et
<literal>--r[fcezi]</literal> ne sont disponibles qu'en mode &cli;.
</para>
</note>
</section>
<!--}}}-->
<!--Usage: {{{-->
<section xml:id="features.commandline.usage">
<title>Exécution de fichiers PHP</title>
<titleabbrev>Utilisation</titleabbrev>
<para>
Il y a 3 façons différentes d'appeler le &cli.sapi; avec du code PHP
à exécuter :
<orderedlist>
<listitem>
<para>
Indiquer à PHP d'exécuter un fichier donné :
</para>
<informalexample>
<screen>
<![CDATA[
php mon_script.php
php -f mon_script.php
]]>
</screen>
</informalexample>
<para>
Les deux méthodes (en utilisant <option>-f</option> ou pas) exécutent le
script contenu dans le fichier <filename>mon_script.php</filename>.
Notez qu'il n'existe pas de restriction sur les fichiers pouvant
être exécutés ; en particulier, il n'est pas nécessaire que l'extension
du fichier soit <literal>.php</literal>.
</para>
</listitem>
<listitem>
<para>
Donner du code PHP à exécuter directement en ligne de commande.
</para>
<informalexample>
<screen>
<![CDATA[
php -r 'print_r(get_defined_constants());'
]]>
</screen>
</informalexample>
<para>
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.
</para>
<note>
<para>
Lisez l'exemple attentivement, il n'y a ni balise d'ouverture, ni balise de fermeture !
L'option <option>-r</option> rend caduque l'utilisation de celles-ci, et les ajouter conduirait
alors à une erreur d'analyse syntaxique.
</para>
</note>
</listitem>
<listitem>
<para>
Alimenter l'entrée standard en code PHP
(<literal>stdin</literal>).
</para>
<para>
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 :
</para>
<informalexample>
<screen>
<![CDATA[
$ some_application | some_filter | php | sort -u > final_output.txt
]]>
</screen>
</informalexample>
</listitem>
</orderedlist>
Il n'est pas possible de combiner ces trois modes d'exécution.
</para>
<para>
Comme toute application shell, l'exécutable PHP accepte
des arguments ; cependant, le script PHP peut aussi en recevoir.
Le nombre d'arguments pouvant être passés à votre script n'est pas limité par PHP
(le shell a une limite en termes 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 <varname>$argv</varname>. Le premier
index (zéro) contient toujours le nom du script appelé depuis la ligne
de commande. Notez que, si le code est exécuté en ligne en utilisant
l'option de ligne commande <option>-r</option>, la valeur de <varname>$argv[0]</varname>
sera <literal>"Standard input code"</literal>; antérieur à PHP 7.2.0,
c'était un tiret (<literal>"-"</literal>) à la place. Cela est aussi vrai si
le code est exécuté via un pipe depuis <constant>STDIN</constant>.
</para>
<para>
Une seconde variable globale, <varname>$argc</varname>, contient le nombre
d'éléments du tableau <varname>$argv</varname>
(<emphasis role="strong">et non pas</emphasis> le nombre d'arguments passés
à votre script).
</para>
<para>
Tant que les arguments passés au script ne commencent pas par
le caractère <literal>-</literal>, il n'y a rien de spécial à surveiller.
Le fait de passer des arguments au script qui commencent par
<literal>-</literal> pose des problèmes car PHP
va penser qu'il doit les interpréter. Pour éviter cela, utilisez le séparateur
<literal>--</literal>. Après cet argument, tous les arguments suivants seront
passés au script sans être modifiés ou analysés par PHP.
</para>
<informalexample>
<screen>
<![CDATA[
# 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' au script, et éviter que PHP ne le traite
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
}
]]>
</screen>
</informalexample>
<para>
Cependant, il y a une autre méthode pour utiliser PHP en script shell ;
la première ligne du script devra être <literal>#!/usr/bin/php</literal>
(à remplacer par le chemin vers le binaire PHP &cli; sur le système sous-jacent).
Le reste du fichier doit contenir le code PHP normal, compris entre les
balises ouvrantes/fermantes. Après avoir mis les droits d'exécution sur le
script (<command>chmod +x test</command>), il peut être exécuté comme un script
shell ou perl habituel :
</para>
<example>
<title>Exécute un script PHP en tant que script shell</title>
<programlisting role="php">
<![CDATA[
#!/usr/bin/php
<?php
var_dump($argv);
?>
]]>
</programlisting>
<para>
En supposant que ce fichier s'appelle <filename>test</filename>, dans le
dossier courant, il est alors possible de faire ceci :
</para>
<screen>
<![CDATA[
$ chmod +x test
$ ./test -h -- foo
array(4) {
[0]=>
string(6) "./test"
[1]=>
string(2) "-h"
[2]=>
string(2) "--"
[3]=>
string(3) "foo"
}
]]>
</screen>
</example>
<para>
Comme vous pouvez le voir, dans ce cas, vous n'avez pas besoin
de faire attention lors du passage de paramètres qui commencent par
<literal>-</literal> à votre script.
</para>
<para>
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 que le système sache quel programme doit exécuter le script.
Sous Windows, vous pouvez associer l'exécutable <filename>php.exe</filename>
avec le double-clic sur les fichiers d'extension <literal>.php</literal>,
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 :
</para>
<para>
<example>
<title>Script prévu pour être exécuté en ligne de commande (script.php)</title>
<programlisting role="php">
<![CDATA[
#!/usr/bin/php
<?php
if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>
C'est une ligne de commande à une option.
Utilisation :
<?php echo $argv[0]; ?> <option>
<option> peut être un mot que vous souhaitez afficher.
Avec les options --help, -help, -h,
et -?, vous obtiendrez cette aide.
<?php
} else {
echo $argv[1];
}
?>
]]>
</programlisting>
</example>
</para>
<para>
Le script ci-dessus inclut la première ligne spéciale indiquant que ce fichier
doit être exécuté par PHP. Nous travaillons ici avec la version &cli;, aussi,
aucun en-tête <acronym>HTTP</acronym> ne sera affiché.
</para>
<para>
Le programme commence par vérifier que l'argument requis est spécifié
(en plus du nom du script, qui est aussi compté). S'il n'est pas présent,
ou si l'argument est <option>--help</option>, <option>-help</option>,
<option>-h</option> ou <option>-?</option>, un message d'aide sera affiché,
en utilisant <varname>$argv[0]</varname> pour afficher dynamiquement le nom
du script tel qu'entré dans la ligne de commande. Sinon, l'argument est affiché
tel qu'il a été entré dans le terminal.
</para>
<para>
Pour exécuter le script ci-dessus sous Unix, vous devez le rendre
exécutable, puis l'appeler avec une commande comme :
<command>script.php echothis</command> ou
<command>script.php -h</command>. Sous Windows, vous pouvez faire un
fichier batch pour cela :
</para>
<para>
<example>
<title>Fichier batch pour exécuter un script PHP en ligne de commande (script.bat)</title>
<programlisting role="winbat">
<![CDATA[
@echo OFF
"C:\php\php.exe" script.php %*
]]>
</programlisting>
</example>
</para>
<para>
En supposant que le programme ci-dessus est nommé
<filename>script.php</filename>, et que l'exécutable &cli;
<filename>php.exe</filename> se trouve dans
<filename>C:\php\php.exe</filename>, ce fichier batch l'exécutera
avec les options que vous lui passez :
<command>script.bat echothis</command> ou
<command>script.bat -h</command>.
</para>
<para>
Voir aussi l'extension <link linkend="ref.readline">Readline</link>,
qui dispose de nombreuses fonctions pour améliorer la convivialité
de des applications PHP en ligne de commande.
</para>
<para>
Sous Windows, PHP peut être configuré pour fonctionner sans avoir
besoin de fournir les extensions <filename>C:\php\php.exe</filename>
ou <literal>.php</literal>, tel que décrit dans
<link linkend="install.windows.commandline">la ligne de commande PHP sous
Microsoft Windows</link>.
</para>
<note>
<para>
Sous Windows, il est recommandé d'exécuter PHP sous un compte utilisateur.
Lorsque PHP est exécuté sous un service réseau, certaines opérations peuvent
échouer, car "Aucun lien entre les noms de compte et les identifiants de
sécurité n'est réalisé".
</para>
</note>
</section>
<!--}}}-->
<!--I/O Streams: {{{-->
<section xml:id="features.commandline.io-streams">
<title>Flux d'entrée/sortie</title>
<titleabbrev>Flux I/O</titleabbrev>
<para>
Le &cli.sapi; définit quelques constantes pour les flux I/O pour
rendre la programmation en ligne de commande plus facile.
</para>
<para>
<table>
<title>Constantes spécifiques CLI</title>
<tgroup cols="2">
<thead>
<row>
<entry>Constante</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>STDIN</constant></entry>
<entry>
<para>
Un flux déjà ouvert vers <literal>stdin</literal>. Ceci évite de
l'ouvrir explicitement avec
<programlisting role="php">
<![CDATA[
<?php
$stdin = fopen('php://stdin', 'r');
?>
]]>
</programlisting>
Si vous voulez lire une seule ligne depuis <literal>stdin</literal>,
vous pouvez utiliser
<programlisting role="php">
<![CDATA[
<?php
$line = trim(fgets(STDIN)); // lit une ligne depuis STDIN
fscanf(STDIN, "%d\n", $number); // lit des nombres depuis STDIN
?>
]]>
</programlisting>
</para>
</entry>
</row>
<row>
<entry><constant>STDOUT</constant></entry>
<entry>
<para>
Un flux déjà ouvert vers <literal>stdout</literal>. Ceci évite de
l'ouvrir explicitement avec
<programlisting role="php">
<![CDATA[
<?php
$stdout = fopen('php://stdout', 'w');
?>
]]>
</programlisting>
</para>
</entry>
</row>
<row>
<entry><constant>STDERR</constant></entry>
<entry>
<para>
Un flux déjà ouvert vers <literal>stderr</literal>.
Ceci évite de l'ouvrir explicitement avec
<programlisting role="php">
<![CDATA[
<?php
$stderr = fopen('php://stderr', 'w');
?>
]]>
</programlisting>
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Ainsi, vous n'avez pas besoin d'ouvrir un flux spécifique pour, par exemple,
<literal>stderr</literal> mais vous pouvez simplement utiliser la constante
correspondante à ce flux :
<programlisting role="shell">
<![CDATA[
php -r 'fwrite(STDERR, "stderr\n");'
]]>
</programlisting>
Vous n'avez pas à clore explicitement ces flux, sachant qu'ils le seront
automatiquement par PHP à la fin de votre script.
</para>
<note>
<para>
Ces constantes ne sont pas disponibles lors d'une lecture d'un
script PHP depuis <literal>stdin</literal>.
</para>
</note>
</section>
<!--}}}-->
<!--Interactive shell: {{{-->
<section xml:id="features.commandline.interactive">
<title>Shell Interactif</title>
<para>
Le &cli.sapi; fournit un shell intéractif lors de l'utilisation
de l'option <option>-a</option> si PHP a été compilé avec l'option <option
role="configure">--with-readline</option>.
Depuis PHP 7.1.0 le shell intéractif est également disponible sur Windows,
si l'<link linkend="book.readline">extension readline</link> est activée.
</para>
<para>
En utilisant le shell interactif, vous avez la possibilité de taper du code PHP
et qu'il soit exécuté directement.
</para>
<example>
<title>Exécution de code en utilisant le shell interactif</title>
<programlisting role="shell">
<![CDATA[
$ php -a
Interactive shell
php > echo 5+8;
13
php > function addTwo($n)
php > {
php { return $n + 2;
php { }
php > var_dump(addtwo(2));
int(4)
php >
]]>
</programlisting>
</example>
<para>
Le shell interactif fournit également une autocomplétion des fonctions,
des constantes, des noms de classes, des variables, des appels aux méthodes
statiques et des constantes de classes en utilisant la touche de tabulation.
</para>
<example>
<title>Auto-complétion en utilisant la touche de tabulation</title>
<simpara>
Le fait de presser deux fois la touche de tabulation lorsqu'il y a plusieurs
complétions possibles affichera une liste de ces complétions :
</simpara>
<programlisting role="shell">
<![CDATA[
php > strp[TAB][TAB]
strpbrk strpos strptime
php > strp
]]>
</programlisting>
<simpara>
Lorsqu'il n'y a qu'une seule complétion possible, presser la touche de tabulation
une seule fois complétera le reste sur la même ligne :
</simpara>
<programlisting role="shell">
<![CDATA[
php > strpt[TAB]ime(
]]>
</programlisting>
<simpara>
La complétion fonctionnera aussi pour les noms qui ont été définis lors
de la session courante du shell interactif :
</simpara>
<programlisting role="shell">
<![CDATA[
php > $fooThisIsAReallyLongVariableName = 42;
php > $foo[TAB]ThisIsAReallyLongVariableName
]]>
</programlisting>
</example>
<para>
Le shell interactif stocke votre historique et peut y accéder en utilisant les touches
haut et bas. L'historique est sauvegardé dans le fichier <filename>~/.php_history</filename>.
</para>
<para>
Le &cli.sapi; fournit 2 directives du &php.ini; :
<parameter>cli.pager</parameter> et <parameter>cli.prompt</parameter>.
La directive <parameter>cli.pager</parameter> permet la définition d'un programme
externe (comme <filename>less</filename>) à utiliser comme pager pour la sortie
au lieu d'afficher directement sur l'écran. La directive
<parameter>cli.prompt</parameter> autorise la modification du prompte
<literal>php &gt;</literal>.
</para>
<para>
Il est également possible de définir des directives du &php.ini;
dans un shell interactif en utilisant des notations raccourcies.
</para>
<example>
<title>Définition de directives du &php.ini; dans un shell interactif</title>
<simpara>
La définition de la directive <parameter>cli.prompt</parameter> :
</simpara>
<programlisting role="shell">
<![CDATA[
php > #cli.prompt=hello world :>
hello world :>
]]>
</programlisting>
<simpara>
En utilisant des backticks, il est possible d'exécuter du code PHP
dans le prompte :
</simpara>
<programlisting role="shell">
<![CDATA[
php > #cli.prompt=`echo date('H:i:s');` php >
15:49:35 php > echo 'hi';
hi
15:49:43 php > sleep(2);
15:49:45 php >
]]>
</programlisting>
<simpara>
Définition du pager à <filename>less</filename> :
</simpara>
<programlisting role="shell">
<![CDATA[
php > #cli.pager=less
php > phpinfo();
(sortie affichée avec less)
php >
]]>
</programlisting>
</example>
<para>
La directive <parameter>cli.prompt</parameter> supporte quelques séquences d'échappements :
<table>
<title>Séquences d'échappements de <parameter>cli.prompt</parameter></title>
<tgroup cols="2">
<thead>
<row>
<entry>Séquence :</entry>
<entry>Description :</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>\e</literal></entry>
<entry>
utilisé pour ajouter des couleurs au prompte. Exemple :
<literal>\e[032m\v \e[031m\b \e[34m\> \e[0m</literal>
</entry>
</row>
<row>
<entry><literal>\v</literal></entry>
<entry>La version de PHP.</entry>
</row>
<row>
<entry><literal>\b</literal></entry>
<entry>
Indique dans quel bloc de PHP nous nous trouvons.
Par exemple, <literal>/*</literal> permet d'indiquer que nous
sommes dans un commentaire multilignes. Le scope externe est représenté
par <literal>php</literal>.
</entry>
</row>
<row>
<entry><literal>\&gt;</literal></entry>
<entry>
Indique le caractère utilisé pour le prompte. Par défaut, ce sera
<literal>&gt;</literal>, mais peut être modifié lorsque le shell se
trouve dans un bloc indéterminé ou dans une chaîne de caractères.
Les caractères possibles sont : <literal>' " {
( &gt;</literal>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<para>
Les fichiers inclus via <link
linkend="ini.auto-prepend-file">auto_prepend_file</link> et <link
linkend="ini.auto-append-file">auto_append_file</link> sont analysés
dans ce mode, mais avec quelques restrictions - i.e. les fonctions
doivent avoir été définies avant l'appel.
</para>
</note>
<section xml:id="features.commandline.interactive.mode">
<title>Interactive mode</title>
<para>
Si l'extension readline n'est pas disponible, antérieur à PHP 8.1.0,
invoquer le &cli.sapi; avec l'option <option>-a</option> fournit le mode intéractif.
Dans ce mode, un script PHP complet est supposé d'être donnée via STDIN,
et après l'interruption avec <literal>CRTL+d</literal> (POSIX) ou <literal>CTRL+z</literal>
suivi de <literal>ENTER</literal> (Windows), ce script sera évalué.
Ceci est basiquement identique à invoquer le &cli.sapi; sans l'option <option>-a</option>.
</para>
<para>
À partir de PHP 8.1.0, invoquer le &cli.sapi; avec l'option <option>-a</option>
échoue, si l'extension readline n'est pas disponible.
</para>
</section>
</section>
<!--}}}-->
<!--Built-in CLI Web Server: {{{-->
<section xml:id="features.commandline.webserver">
<title>Serveur web interne</title>
<warning>
<para>
Ce serveur web est prévu pour aider dans le développement des applications.
Il peut également être utile pour les tests, et pour les démonstrations
d'applications qui sont exécutées dans des environnements contrôlés.
Mais par contre, il n'a pas été conçu pour être un serveur web complet.
Aussi, il ne devrait pas être utilisé dans un réseau public.
</para>
</warning>
<para>
Le &cli.sapi; fournit un serveur web interne.
</para>
<para>
Le serveur web s'exécute sur un seul processus single-threaded,
les applications PHP seront retardés/suspendues si une requête est bloquée.
</para>
<para>
Les requêtes URI sont servies depuis le dossier de travail courant
où PHP a été démarré, à moins que l'option -t ne soit utilisée pour spécifier
explicitement un document racine. Si une requête URI ne spécifie
pas un fichier, alors le fichier index.php ou le fichier
index.html du dossier courant sera retourné. Si aucun de ces fichiers n'existe,
la recherche d'un fichier index.php et index.html se poursuivra dans le dossier
parent et ainsi de suite jusqu'à ce qu'un de ces fichier ne soit trouvé ou
que le dossier racine ne soit atteint. Si un fichier index.php ou index.html
est trouvé, il sera retourné et $_SERVER['PATH_INFO'] sera défini comme la
dernière partie de l'URI. Sinon, un code réponse 404 sera retourné.
</para>
<para>
Si un fichier PHP est fourni dans la ligne de commande lorsque le serveur web
est démarré, il sera traité comme un script "routeur".
Le script sera exécuté au début de chaque requête HTTP. Si ce script retourne
&false;, alors la ressource demandée est retournée telle quelle.
Sinon, la sortie du script est retournée au navigateur.
</para>
<para>
Les types MIME standards sont retournés pour les fichiers avec les extensions :
<simplelist type="inline">
<member><literal>.3gp</literal></member>
<member><literal>.apk</literal></member>
<member><literal>.avi</literal></member>
<member><literal>.bmp</literal></member>
<member><literal>.css</literal></member>
<member><literal>.csv</literal></member>
<member><literal>.doc</literal></member>
<member><literal>.docx</literal></member>
<member><literal>.flac</literal></member>
<member><literal>.gif</literal></member>
<member><literal>.gz</literal></member>
<member><literal>.gzip</literal></member>
<member><literal>.htm</literal></member>
<member><literal>.html</literal></member>
<member><literal>.ics</literal></member>
<member><literal>.jpe</literal></member>
<member><literal>.jpeg</literal></member>
<member><literal>.jpg</literal></member>
<member><literal>.js</literal></member>
<member><literal>.kml</literal></member>
<member><literal>.kmz</literal></member>
<member><literal>.m4a</literal></member>
<member><literal>.mov</literal></member>
<member><literal>.mp3</literal></member>
<member><literal>.mp4</literal></member>
<member><literal>.mpeg</literal></member>
<member><literal>.mpg</literal></member>
<member><literal>.odp</literal></member>
<member><literal>.ods</literal></member>
<member><literal>.odt</literal></member>
<member><literal>.oga</literal></member>
<member><literal>.ogg</literal></member>
<member><literal>.ogv</literal></member>
<member><literal>.pdf</literal></member>
<member><literal>.png</literal></member>
<member><literal>.pps</literal></member>
<member><literal>.pptx</literal></member>
<member><literal>.qt</literal></member>
<member><literal>.svg</literal></member>
<member><literal>.swf</literal></member>
<member><literal>.tar</literal></member>
<member><literal>.text</literal></member>
<member><literal>.tif</literal></member>
<member><literal>.txt</literal></member>
<member><literal>.wav</literal></member>
<member><literal>.webm</literal></member>
<member><literal>.wmv</literal></member>
<member><literal>.xls</literal></member>
<member><literal>.xlsx</literal></member>
<member><literal>.xml</literal></member>
<member><literal>.xsl</literal></member>
<member><literal>.xsd</literal></member>
<member><literal>.zip</literal></member>
</simplelist>
.
</para>
<simpara>
À partir de PHP 7.4.0, le serveur web intégré peut être configuré pour bifurquer plusieurs
travailleurs afin de tester du code nécessitant plusieurs requêtes concurrentes
au serveur web intégré.
Définissez la variable d'environnement <envar>PHP_CLI_SERVER_WORKERS</envar> sur le
nombre de travailleurs souhaité avant de démarrer le serveur.
</simpara>
<note>
<simpara>Cette fonctionnalité n'est pas prise en charge sur Windows.</simpara>
</note>
<warning>
<para>
Cette fonctionnalité <emphasis>expérimentale</emphasis> n'est <emphasis>pas</emphasis>
destinée à une utilisation en production. En général, le Serveur Web intégré
n'est <emphasis>pas</emphasis> destiné à une utilisation en production.
</para>
</warning>
<table>
<title>Changelog</title>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>7.4.0</entry>
<entry>
Le serveur web intégré peut être configuré pour fork en de multiple
workers pour tester du code qui nécéssite plusieurs requêtes concurrentes
au serveur web intégré. Définir la variable d'environnement
<envar>PHP_CLI_SERVER_WORKERS</envar> au nombre désiré de workers avant
de démarrer le serveur. Ceci n'est pas supporté sous Windows.
<warning>
<para>
Ce comportement <emphasis>expérimental</emphasis> <emphasis>n'est pas</emphasis>
prévu pour un usage en production. Plus générallement, le serveur web intégré
<emphasis>n'est pas</emphasis> prévu pour un usage en production.
</para>
</warning>
</entry>
</row>
</tbody>
</tgroup>
</table>
<example>
<title>Démarrage du serveur web</title>
<programlisting role="shell">
<![CDATA[
$ cd ~/public_html
$ php -S localhost:8000
]]>
</programlisting>
<para>
Le terminal affichera :
</para>
<screen>
<![CDATA[
PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit
]]>
</screen>
<para>
Après des requêtes URI sur http://localhost:8000/ et
http://localhost:8000/myscript.html, le terminal affichera quelques choses
comme :
</para>
<screen>
<![CDATA[
PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit.
[Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
[Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
[Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
[Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
[Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read
]]>
</screen>
<para>
Noter qu'avant PHP 7.4.0, les ressources statiques en lien symbolique
ne sont pas accessibles sous Windows, tant que le script routeur
ne le gère pas.
</para>
</example>
<example>
<title>Démarrage avec un dossier racine spécifique</title>
<programlisting role="shell">
<![CDATA[
$ cd ~/public_html
$ php -S localhost:8000 -t foo/
]]>
</programlisting>
<para>
Le terminal affichera :
</para>
<screen>
<![CDATA[
PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
Listening on localhost:8000
Document root is /home/me/public_html/foo
Press Ctrl-C to quit
]]>
</screen>
</example>
<example>
<title>Utilisation d'un script routeur</title>
<para>
Dans cet exemple, le fait de demander des images les affichera,
mais les requêtes pour les fichiers HTML afficheront
"Bienvenue chez PHP !".
</para>
<programlisting role="php">
<![CDATA[
<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
return false; // retourne la requête telle quelle.
} else {
echo "<p>Bienvenue chez PHP !</p>";
}
?>]]>
</programlisting>
<programlisting role="shell">
<![CDATA[
$ php -S localhost:8000 router.php
]]>
</programlisting>
</example>
<example>
<title>Vérification de l'utilisation CLI du serveur Web</title>
<para>
Pour ré-utiliser un script router du framework lors du
développement avec le CLI du serveur web et ensuite, continuez
de l'utiliser avec un serveur web de production :
</para>
<programlisting role="php">
<![CDATA[
<?php
// router.php
if (php_sapi_name() == 'cli-server') {
/* Activation de la route statique et retourne FALSE */
}
/* on continue avec les opérations d'un index.php normal */
?>]]>
</programlisting>
<programlisting role="shell">
<![CDATA[
$ php -S localhost:8000 router.php
]]>
</programlisting>
</example>
<example>
<title>Gestion des types de fichiers non supportés</title>
<para>
Si vous devez servir une ressource statique pour laquelle le type
MIME n'est pas géré par le CLI du serveur web, utilisez ceci :
</para>
<programlisting role="php">
<![CDATA[
<?php
// router.php
$path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
if ($path["extension"] == "el") {
header("Content-Type: text/x-script.elisp");
readfile($_SERVER["SCRIPT_FILENAME"]);
}
else {
return FALSE;
}
?>]]>
</programlisting>
<programlisting role="shell">
<![CDATA[
$ php -S localhost:8000 router.php
]]>
</programlisting>
</example>
<example>
<title>Accès au CLI du serveur web depuis une machine distante</title>
<para>
Vous pouvez rendre le serveur web accessible sur le port 8000
pour toutes les interfaces avec :
</para>
<programlisting role="shell">
<![CDATA[
$ php -S 0.0.0.0:8000
]]>
</programlisting>
<warning>
<para>
Le serveur web intégré ne doit pas être utilisé sur un réseau public.
</para>
</warning>
</example>
</section>
<!--}}}-->
<section xml:id="features.commandline.ini">
<title>Configurations INI</title>
<para>
<table>
<title>Options de configuration CLI SAPI</title>
<tgroup cols="4">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Default;</entry>
<entry>&Changeable;</entry>
<entry>&Changelog;</entry>
</row>
</thead>
<tbody xml:id="features.commandline.ini.list">
<row>
<entry><link linkend="ini.cli-server.color">cli_server.color</link></entry>
<entry>"0"</entry>
<entry><constant>INI_ALL</constant></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
&ini.descriptions.title;
<para>
<variablelist>
<varlistentry xml:id="ini.cli-server.color">
<term>
<parameter>cli_server.color</parameter>
<type>bool</type>
</term>
<listitem>
<para>
Active le serveur web de développement interne à utiliser
la coloration ANSI du code dans la sortie du terminal.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
</chapter>
<!-- 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:"~/.phpdoc/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
-->
Reference in New Issue View Git Blame Copy Permalink