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

<!-- EN-Revision: 96b10a98853e3b8236504e5775f95eb4a15c82c3 Maintainer: PhilDaiguille Status: ready -->

<!-- Reviewed: no -->

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

<title>Utilización de la línea de comandos</title>

<titleabbrev>Utilización de líneas de comando</titleabbrev>

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

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

<title>Introducción</title>

<para>

El propósito principal de &cli.sapi; es el desarrollo de aplicaciones shell con PHP. Las diferencias entre &cli.sapi; y otros <acronym>SAPI</acronym> se explican en este capítulo. Es importante mencionar que &cli; y <acronym>CGI</acronym> son <acronym>SAPI</acronym> diferentes a pesar de que puedan compartir la mayor parte de sus comportamientos.

</para>

<para>

El &cli.sapi; se activa por defecto utilizando la opción <option role="configure">--enable-cli</option>, pero se puede desactivar utilizando la opción <option role="configure">--disable-cli</option> al ejecutar el comando <command>./configure</command>.

</para>

<para>

El nombre, la ubicación y la existencia de los binarios &cli;/<acronym>CGI</acronym> dependerán de la forma en que PHP esté instalado en su sistema. Por defecto, al ejecutar <command>make</command>, ambos binarios <acronym>CGI</acronym> y &cli; se compilan y se nombran respectivamente <filename>sapi/cgi/php</filename> y <filename>sapi/cli/php</filename> en su directorio fuente PHP. Se observará que ambos se nombran <filename>php</filename>. Lo que sucede después durante el <command>make install</command> depende de su línea de configuración. Si un módulo <acronym>SAPI</acronym>, como apxs, se ha elegido durante la configuración, o si la opción <option role="configure"> --disable-cgi</option> se ha activado, el &cli; se copia en <filename>{PREFIX}/bin/php</filename> durante el <command>make install</command>, de lo contrario, el <acronym>CGI</acronym> se colocará aquí. Si, por ejemplo, <option role="configure">--with-apxs</option> figura en su línea de configuración, el &cli; se copia en <filename>{PREFIX}/bin/php</filename> durante el <command>make install</command>. Si se desea forzar la instalación del binario <acronym>CGI</acronym>, ejecute <command>make install-cli</command> después del <command>make install</command>. De lo contrario, también se puede especificar <option role="configure">--disable-cgi</option> en su línea de configuración.

</para>

<note>

<para>

Dado que ambas opciones <option role="configure">--enable-cli</option> y <option role="configure">--enable-cgi</option> están activadas por defecto, tener simplemente <option role="configure">--enable-cli</option> en su línea de configuración no implica necesariamente que el CLI se renombre a <filename>{PREFIX}/bin/php</filename> durante el <command>make install</command>.

</para>

</note>

<para>

El binario &cli; se distribuye en el directorio principal bajo el nombre de <filename>php.exe</filename> en Windows. La versión <acronym>CGI</acronym> se distribuye bajo el nombre de <filename>php-cgi.exe</filename>. Además, un archivo <filename>php-win.exe</filename> se distribuye si PHP se configura utilizando la opción de configuración <option role="configure">--enable-cli-win32</option>. Este archivo hace lo mismo que la versión &cli;, excepto que no muestra nada y no proporciona una consola.

</para>

<note>

<title>¿Qué SAPI está instalado?</title>

<para>

Desde un terminal, ejecutar <command>php -v</command> indicará si <filename>php</filename> está en versión <acronym>CGI</acronym> o &cli;. También se puede consultar la función <function>php_sapi_name</function> y la constante <constant>PHP_SAPI</constant>.

</para>

</note>

<note>

<para>

Una página <literal>man</literal> de manual Unix está disponible escribiendo <command>man php</command> en el intérprete de comandos.

</para>

</note>

</section>

<!--}}}-->

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

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

<title>Diferencia con otros <acronym>SAPI</acronym>s</title>

<para>

Las diferencias más notables entre el &cli; <acronym>SAPI</acronym> y los otros <acronym>SAPI</acronym> son:

<itemizedlist>

<listitem>

<para>

A diferencia del <acronym>CGI</acronym> <acronym>SAPI</acronym>, ningún encabezado HTTP se escribe en el resultado.

</para>

<para>

Aunque el <acronym>CGI</acronym> <acronym>SAPI</acronym> proporciona una forma de eliminar los encabezados HTTP, no es posible activar los encabezados HTTP en el &cli.sapi;.

</para>

<para>

&cli; se ejecuta en modo silencioso por defecto, aunque las opciones <option>-q</option> y <option>--no-header</option> se mantienen para mantener la compatibilidad con versiones anteriores de <acronym>CGI</acronym>.

</para>

<para>

No cambia el directorio actual al del script. (Las opciones <option>-C</option> y <option>--no-chdir</option> se mantienen por razones de compatibilidad).

</para>

<para>

Mensajes de error en texto plano (sin formato <acronym>HTML</acronym>).

</para>

</listitem>

<listitem>

<para>

Hay varias directivas del &php.ini; que son ignoradas por el &cli.sapi;, ya que no tienen sentido en un entorno shell:

</para>

<para>

<table>

<title>Directivas &php.ini; ignoradas</title>

<tgroup cols="3">

<thead>

<row>

<entry>Directiva</entry>

<entry>Valor por defecto para &cli; <acronym>SAPI</acronym></entry>

<entry>Comentario</entry>

</row>

</thead>

<tbody>

<row>

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

<entry>&false;</entry>

<entry>

Por defecto a &false;, ya que puede ser bastante difícil leer mensajes de error en un terminal cuando están enterrados en etiquetas <acronym>HTML</acronym> no interpretadas.

</entry>

</row>

<row>

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

<entry>&true;</entry>

<entry>

En un terminal, generalmente es deseable que cualquier salida de <function>print</function>, <function>echo</function> y otros, se muestre inmediatamente, y no se coloque en un búfer. Sin embargo, siempre es posible utilizar <link linkend="ref.outcontrol">la bufferización de salida</link> si se desea retrasar una salida, o bien manipular su contenido una última vez.

</entry>

</row>

<row>

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

<entry>0 (sin límite)</entry>

<entry>

PHP en un terminal es susceptible de ser utilizado para tareas mucho más diversas que en scripts web, y dado que esto generalmente toma mucho tiempo, este parámetro se establecerá por defecto a 0 permitiendo así ser ilimitado.

</entry>

</row>

<row>

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

<entry>&true;</entry>

<entry>

<para>

El establecimiento de esta directiva a &true; significa que los scripts ejecutados a través del <acronym>SAPI</acronym> &cli; siempre tendrán acceso a <emphasis>argc</emphasis> (representando el número de argumentos pasados a la aplicación) y <emphasis>argv</emphasis> (el array que contiene los argumentos pasados).

</para>

<para>

Las variables PHP <varname>$argc</varname> y <varname>$argv</varname> se definen y rellenan automáticamente con los valores apropiados, al utilizar el <acronym>SAPI</acronym> &cli;. Estos valores también pueden encontrarse en la variable <varname>$_SERVER</varname>, por ejemplo: <varname>$_SERVER['argv']</varname>.

</para>

<warning>

<para>

La presencia de <varname>$argv</varname> o <varname>$_SERVER['argv']</varname> no es una indicación fiable de que un script se está ejecutando desde la línea de comandos, ya que estas variables pueden definirse en otros contextos cuando <link linkend="ini.register-argc-argv">register_argc_argv</link> está activado. El valor devuelto por <function>php_sapi_name</function> debe verificarse en su lugar.

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

if (php_sapi_name() === 'cli') {

echo "¡Este script se está ejecutando desde la línea de comandos!\n";

}

]]>

</programlisting>

</informalexample>

</para>

</warning>

</entry>

</row>

<row>

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

<entry>&false;</entry>

<entry>

<para>

Aunque esta configuración INI está codificada a &false;, las funciones relacionadas con <link linkend="book.outcontrol">la visualización del búfer</link> están disponibles.

</para>

</entry>

</row>

<row>

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

<entry>&false;</entry>

<entry>

<para>

El PHP &cli; no soporta GET, POST y la carga de archivos.

</para>

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<note>

<para>

Estas directivas no pueden inicializarse con otros valores en el archivo &php.ini; o por cualquier otro método. Es una limitación, ya que estos valores por defecto se aplican una vez que todos los otros archivos de configuración han sido analizados. Sin embargo, estos valores pueden modificarse durante la ejecución (lo cual no es lógico para ciertas directivas, como <link linkend="ini.register-argc-argv">register_argc_argv</link>).

</para>

</note>

<note>

<para>

Se recomienda establecer <link linkend="ini.ignore-user-abort">ignore_user_abort</link> para los scripts en línea de comandos. Consulte la función <function>ignore_user_abort</function> para más información.

</para>

</note>

</listitem>

<listitem>

<para>

Para facilitar el trabajo en un entorno shell, se definen varias constantes para los <link linkend="features.commandline.io-streams">flujos I/O</link>.

</para>

</listitem>

<listitem>

<para>

El &cli.sapi; <emphasis role="strong">no transforma</emphasis> el directorio actual en el directorio de ejecución del script.

</para>

<example>

<title>

Ejemplo que muestra la diferencia con el <acronym>SAPI</acronym> <acronym>CGI</acronym>:

</title>

<programlisting role="php">

<![CDATA[

<?php

// Una prueba simple: muestra el directorio de ejecución */

echo getcwd(), "\n";

?>

]]>

</programlisting>

<para>

Cuando se utiliza la versión <acronym>CGI</acronym>, la salida será:

</para>

<screen>

<![CDATA[

$ pwd

/tmp

$ php -q otro_directorio/test.php

/tmp/otro_directorio

]]>

</screen>

<para>

Esto muestra claramente que PHP cambia el directorio actual y utiliza el directorio del script ejecutado.

</para>

<para>

Al utilizar el &cli.sapi;, se obtiene:

</para>

<screen>

<![CDATA[

$ pwd

/tmp

$ php -f otro_directorio/test.php

/tmp

]]>

</screen>

<para>

Esto proporciona mucha más flexibilidad al escribir scripts shell con PHP.

</para>

</example>

<note>

<para>

El <acronym>CGI</acronym> <acronym>SAPI</acronym> se comporta de la misma manera que el &cli.sapi;, pasándole la opción <option>-C</option>, cuando se invoca en la línea de comandos.

</para>

</note>

</listitem>

</itemizedlist>

</para>

</section>

<!--}}}-->

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

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

<title>Opciones de línea de comandos</title>

<titleabbrev>Opciones</titleabbrev>

<para>

La lista de opciones de línea de comandos proporcionadas por PHP está disponible en cualquier momento ejecutando PHP con la opción <option>-h</option>:

<screen>

<![CDATA[

Uso: php [opciones] [-f] <archivo> [--] [args...]

php [opciones] -r <código> [--] [args...]

php [opciones] [-B <begin_code>] -R <código> [-E <end_code>] [--] [args...]

php [opciones] [-B <begin_code>] -F <archivo> [-E <end_code>] [--] [args...]

php [opciones] -- [args...]

php [opciones] -a

-a Ejecutar de forma interactiva

-c <ruta>|<archivo> Buscar el archivo php.ini en este directorio

-n No se utilizará ningún archivo php.ini

-d foo[=bar] Definir la entrada INI foo con el valor 'bar'

-e Generar información extendida para el depurador/perfilador

-f <archivo> Analizar y ejecutar <archivo>.

-h Esta ayuda

-i Información de PHP

-l Verificación de sintaxis únicamente (lint)

-m Mostrar módulos compilados

-r <código> Ejecutar el código PHP sin usar etiquetas de script <?..?>

-B <begin_code> Ejecutar <begin_code> antes de procesar las líneas de entrada

-R <código> Ejecutar el código PHP para cada línea de entrada

-F <archivo> Analizar y ejecutar <archivo> para cada línea de entrada

-E <end_code> Ejecutar <end_code> después de procesar todas las líneas de entrada

-H Ocultar cualquier argumento pasado de herramientas externas.

-S <dirección>:<puerto> Ejecutar con el servidor web integrado.

-t <docroot> Especificar el directorio raíz del documento para el servidor web integrado.

-s Salida de sintaxis HTML resaltada.

-v Número de versión

-w Salida de código fuente con comentarios y espacios en blanco eliminados.

-z <archivo> Cargar la extensión Zend <archivo>.

args... Argumentos pasados al script. Usar -- args cuando el primer argumento

comienza con - o el script se lee desde stdin

--ini Mostrar nombres de archivos de configuración

--rf <nombre> Mostrar información sobre la función <nombre>.

--rc <nombre> Mostrar información sobre la clase <nombre>.

--re <nombre> Mostrar información sobre la extensión <nombre>.

--rz <nombre> Mostrar información sobre la extensión Zend <nombre>.

--ri <nombre> Mostrar configuración para la extensión <nombre>.

]]>

</screen>

</para>

<para>

<table>

<title>Opciones de línea de comandos</title>

<tgroup cols="2">

<thead>

<row>

<entry>Opción</entry>

<entry>Opción larga</entry>

<entry>Descripción</entry>

</row>

</thead>

<tbody>

<row>

<entry>-a</entry>

<entry>--interactive</entry>

<entry>

<para>

Lanza PHP de forma interactiva. Para más información, consulte la documentación sobre el <link linkend="features.commandline.interactive">shell interactivo</link>.

</para>

</entry>

</row>

<row>

<entry>-b</entry>

<entry>--bindpath</entry>

<entry>

<para>

Enlaza la ruta para los externos, en modo servidor FASTCGI (solo <acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-C</entry>

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

<entry>

<para>

No ir al directorio del script (solo <acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-q</entry>

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

<entry>

<para>

Modo silencioso. Suprime la salida de los encabezados <acronym>HTTP</acronym> (solo <acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-T</entry>

<entry>--timing</entry>

<entry>

<para>

Mide el tiempo de ejecución del script, repetido <varname>count</varname> veces (solo <acronym>CGI</acronym>).

</para>

</entry>

</row>

<row>

<entry>-c</entry>

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

<entry>

<para>

Especifica el nombre del directorio en el que se encuentra el archivo &php.ini;, o bien especifica un archivo de configuración (<literal>INI</literal>) directamente (que no se llama necesariamente &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 esta opción no se especifica, &php.ini; se buscará en los <link linkend="configuration.file">lugares por defecto</link>.

</para>

</entry>

</row>

<row>

<entry>-n</entry>

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

<entry>

<para>

Ignora completamente &php.ini;.

</para>

</entry>

</row>

<row>

<entry>-d</entry>

<entry>--define</entry>

<entry>

<para>

Define un valor personalizado para cualquier directiva de configuración del archivo &php.ini;. La sintaxis es:

<screen>

<![CDATA[

-d configuration_directive[=value]

]]>

</screen>

</para>

<para>

<example>

<title>Ejemplo de uso de <literal>-d</literal> para establecer una configuración INI</title>

<screen>

<![CDATA[

# La omisión del valor conduce a dar el valor de "1"

$ php -d max_execution_time

-r '$foo = ini_get("max_execution_time"); var_dump($foo);'

string(1) "1"

# Pasar un valor vacío conduce a dar el valor de ""

php -d max_execution_time=

-r '$foo = ini_get("max_execution_time"); var_dump($foo);'

string(0) ""

# La directiva de configuración será cualquier valor pasado después del carácter '='

$ 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>

Genera información extendida para la depuración y el perfilado.

</para>

</entry>

</row>

<row>

<entry>-f</entry>

<entry>--file</entry>

<entry>

<para>

Analiza y ejecuta el archivo especificado. La opción <option>-f</option> es opcional y puede omitirse. El nombre del archivo es suficiente.

</para>

</entry>

</row>

<row>

<entry>-h y -?</entry>

<entry>--help y --usage</entry>

<entry>

Muestra información sobre la lista actual de opciones de la línea de comandos, así como su descripción.

</entry>

</row>

<row>

<entry>-i</entry>

<entry>--info</entry>

<entry>

Llama a la función <function>phpinfo</function> y muestra el resultado. Si PHP no funciona correctamente, se recomienda utilizar el comando <command>php -i</command> y ver si no hay errores mostrados antes o después de la tabla de información. No olvide que el resultado de esta opción, si se utiliza el modo <acronym>CGI</acronym>, está en formato <acronym>HTML</acronym> y, por lo tanto, es de tamaño considerable.

</entry>

</row>

<row>

<entry>-l</entry>

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

<entry>

<para>

Verifica la sintaxis pero no ejecuta el código PHP dado. La entrada proveniente de la entrada estándar se procesará si no se especifica ningún nombre de archivo, de lo contrario, cada archivo especificado se verificará. En caso de éxito, se muestra el mensaje <literal>No syntax errors detected in &lt;filename&gt;</literal> (Literalmente, no se detectaron errores de sintaxis en el archivo) en la salida estándar. En caso de error, se muestra el mensaje <literal>Errors parsing &lt;filename&gt;</literal> (Literalmente, error de análisis en el archivo filename) junto con los mensajes de error detectados por el analizador mismo. Si se encuentran errores en los archivos especificados (o en la entrada estándar), el código de retorno del shell se establece en <literal>-1</literal>, de lo contrario, el código de retorno del shell se establece en <literal>0</literal>.

</para>

<para>

Esta opción no detecta errores fatales (por ejemplo, funciones no definidas) que requieren la ejecución del código.

</para>

<note>

<para>

Antes de PHP 8.3.0, solo se podía especificar un nombre de archivo para verificar.

</para>

</note>

<note>

<para>

Esta opción no funciona con la opción <option>-r</option>.

</para>

</note>

</entry>

</row>

<row>

<entry>-m</entry>

<entry>--modules</entry>

<entry>

<para>

<example>

<title>Mostrar módulos internos (y cargados) de PHP y 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>

Permite la ejecución de PHP directamente en la línea de comandos. Las etiquetas de PHP (<literal>&lt;?php</literal> y <literal>?&gt;</literal>) <emphasis role="strong">no son</emphasis> necesarias y causarán un error de análisis si están presentes.

</para>

<note>

<para>

Se debe prestar especial atención al utilizar esta opción de PHP para que no haya colisión con las sustituciones de variables en la línea de comandos realizadas por el shell.

</para>

<example>

<title>Error de sintaxis al usar comillas dobles</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>

El problema aquí es que el shell (sh/bash) realiza una sustitución de variables, incluso con las comillas dobles <literal>"</literal>. Dado que la variable <varname>$foo</varname> probablemente no está definida en el shell, se reemplaza por nada, lo que hace que el código pasado a PHP para ejecutar sea:

</para>

<informalexample>

<screen>

<![CDATA[

$ php -r " = get_defined_constants();"

]]>

</screen>

</informalexample>

<para>

La solución a este problema es utilizar comillas simples <literal>'</literal>. Las variables de estas cadenas no serán sustituidas por sus valores por el shell.

</para>

<example>

<title>Uso de comillas simples para evitar una sustitución por el 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 se utiliza un shell diferente de sh/bash, pueden encontrarse otros problemas; si es apropiado, se puede abrir un informe de errores a través de <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>. Es muy fácil tener problemas al intentar incluir variables de shell en el código, o al usar las barras invertidas para la protección. ¡Se le ha advertido!

</para>

</note>

<note>

<para>

<option>-r</option> está disponible con el &cli.sapi; pero no con el <acronym>SAPI</acronym> <emphasis>CGI</emphasis>.

</para>

</note>

<note>

<para>

Esta opción solo se utiliza para cosas simples. Por lo tanto, algunas directivas de configuración (por ejemplo, <link linkend="ini.auto-prepend-file">auto_prepend_file</link> y <link linkend="ini.auto-append-file">auto_append_file</link>) se ignoran en este modo.

</para>

</note>

</entry>

</row>

<row>

<entry>-B</entry>

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

<entry>

<para>

Código PHP a ejecutar antes de procesar stdin.

</para>

</entry>

</row>

<row>

<entry>-R</entry>

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

<entry>

<para>

Código PHP a ejecutar para cada línea de entrada.

</para>

<para>

Hay dos variables especiales disponibles en este modo: <varname>$argn</varname> y <varname>$argi</varname>. <varname>$argn</varname> debe contener la línea PHP procesada en ese momento, mientras que <varname>$argi</varname> debe contener el número de la línea.

</para>

</entry>

</row>

<row>

<entry>-F</entry>

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

<entry>

<para>

Archivo PHP a ejecutar para cada línea de entrada.

</para>

</entry>

</row>

<row>

<entry>-E</entry>

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

<entry>

<para>

Código PHP a ejecutar después de realizar la entrada.

</para>

<para>

<example>

<title>Ejemplo de uso de las opciones <option>-B</option>, <option>-R</option> y <option>-E</option> para contar el número de líneas de un proyecto.</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>

Inicia el <link linkend="features.commandline.webserver">servidor web interno</link>. Disponible desde 5.4.0.

</para>

</entry>

</row>

<row>

<entry>-t</entry>

<entry>--docroot</entry>

<entry>

Especifica la raíz de los documentos para el <link linkend="features.commandline.webserver">servidor web interno</link>.

</entry>

</row>

<row>

<entry>-s</entry>

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

<entry>

<para>

Muestra el código con colorización de sintaxis.

</para>

<para>

Esta opción utiliza el mecanismo interno para analizar el archivo y escribir una versión coloreada del código fuente en formato HTML. Tenga en cuenta que esta opción solo genera un bloque HTML, con las etiquetas HTML <literal>&lt;code&gt; [...] &lt;/code&gt;</literal>, sin encabezados HTML.

</para>

<note>

<para>

Esta opción no funciona con la opción <option>-r</option>.

</para>

</note>

</entry>

</row>

<row>

<entry>-v</entry>

<entry>--version</entry>

<entry>

<para><example>

<title>Uso de la opción <option>-v</option> para recuperar el nombre del <acronym>SAPI</acronym> así como la versión de PHP y 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>

Muestra el código fuente sin comentarios ni espacios.

</para>

<note>

<para>

Esta opción no funciona con la opción <option>-r</option>.

</para>

</note>

</entry>

</row>

<row>

<entry>-z</entry>

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

<entry>

<para>

Carga una extensión Zend. Si y solo si se proporciona un archivo, PHP intentará cargar esta extensión en el directorio predeterminado de las bibliotecas en su sistema (generalmente especificado con <filename>/etc/ld.so.conf</filename> en Linux, por ejemplo). Pasar un nombre de archivo con la ruta completa hará que PHP use este archivo, sin buscar en los directorios habituales. Una ruta de directorio relativa, que incluya información sobre el directorio, indicará a PHP que debe buscar las extensiones solo en ese directorio.

</para>

</entry>

</row>

<row>

<entry></entry>

<entry>--ini</entry>

<entry>

<para>

Muestra los nombres de los archivos de configuración y los directorios analizados.

<example>

<title>Ejemplo con <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>

Muestra información sobre la función dada o el método de una clase (es decir, número y nombre de los parámetros).

</para>

<para>

Esta opción solo está disponible si PHP se ha compilado con soporte <link linkend="book.reflection">Reflection</link>.

</para>

<para>

<example>

<title>Ejemplo con <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>

Muestra información sobre la clase dada (lista de constantes, propiedades y métodos).

</para>

<para>

Esta opción solo está disponible si PHP se ha compilado con soporte <link linkend="book.reflection">Reflection</link>.

</para>

<para>

<example>

<title>Ejemplo con <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>

Muestra la información sobre la extensión dada (lista las opciones del &php.ini;, las funciones definidas, las constantes y las clases).

</para>

<para>

Esta opción solo está disponible si PHP se ha compilado con soporte <link linkend="book.reflection">Reflection</link>.

</para>

<para>

<example>

<title>Ejemplo con <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>

Muestra la información de configuración para la extensión Zend proporcionada (la misma información que la devuelta por la función <function>phpinfo</function>).

</para>

</entry>

</row>

<row>

<entry>--ri</entry>

<entry>--rextinfo</entry>

<entry>

<para>

Muestra la información de configuración para la extensión dada (la misma información devuelta por la función <function>phpinfo</function>). Las informaciones de configuración internas están disponibles utilizando el nombre de extensión "main" o "core".

</para>

<para>

<example>

<title>Ejemplo con <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>

Las opciones <literal>-rBRFEH</literal>, <literal>--ini</literal> y <literal>--r[fcezi]</literal> solo están disponibles en modo &cli;.

</para>

</note>

</section>

<!--}}}-->

<!--Usage: {{{-->

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

<title>Ejecución de archivos PHP</title>

<titleabbrev>Utilización</titleabbrev>

<para>

Hay 3 formas diferentes de llamar al &cli.sapi; con código PHP a ejecutar:

<orderedlist>

<listitem>

<para>

Indicar a PHP que ejecute un archivo dado:

</para>

<informalexample>

<screen>

<![CDATA[

php mon_script.php

php -f mon_script.php

]]>

</screen>

</informalexample>

<para>

Ambos métodos (usando <option>-f</option> o no) ejecutan el script contenido en el archivo <filename>mon_script.php</filename>. Tenga en cuenta que no existe restricción sobre los archivos que se pueden ejecutar; en particular, no es necesario que la extensión del archivo sea <literal>.php</literal>.

</para>

</listitem>

<listitem>

<para>

Dar código PHP a ejecutar directamente en la línea de comandos.

</para>

<informalexample>

<screen>

<![CDATA[

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

]]>

</screen>

</informalexample>

<para>

En este caso, se debe prestar especial atención a las variables de entorno, que serán reemplazadas, y a las comillas, que tienen significados especiales en la línea de comandos.

</para>

<note>

<para>

Lea el ejemplo con atención, ¡no hay etiquetas de apertura ni de cierre! La opción <option>-r</option> hace que el uso de estas etiquetas sea innecesario, y agregarlas conduciría a un error de análisis sintáctico.

</para>

</note>

</listitem>

<listitem>

<para>

Alimentar la entrada estándar con código PHP (<literal>stdin</literal>).

</para>

<para>

Esto proporciona la posibilidad de crear código PHP dinámicamente, luego proporcionarlo a PHP y, finalmente, procesarlo nuevamente en el shell. Aquí hay un ejemplo ficticio:

</para>

<informalexample>

<screen>

<![CDATA[

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

]]>

</screen>

</informalexample>

</listitem>

</orderedlist>

No es posible combinar estos tres modos de ejecución.

</para>

<para>

Como cualquier aplicación shell, el ejecutable PHP acepta argumentos; sin embargo, el script PHP también puede recibirlos. El número de argumentos que se pueden pasar a su script no está limitado por PHP (el shell tiene un límite en términos de número de caracteres que se pueden pasar. Generalmente, no alcanzará este límite). Los argumentos pasados al script se transmitirán a través de la variable array <varname>$argv</varname>. El primer índice (cero) contiene siempre el nombre del script llamado desde la línea de comandos. Tenga en cuenta que, si el código se ejecuta en línea usando la opción de línea de comandos <option>-r</option>, el valor de <varname>$argv[0]</varname> será <literal>"Standard input code"</literal>; anterior a PHP 7.2.0, era un guion (<literal>"-"</literal>) en su lugar. Esto también es cierto si el código se ejecuta a través de un pipe desde <constant>STDIN</constant>.

</para>

<para>

Una segunda variable global, <varname>$argc</varname>, contiene el número de elementos del array <varname>$argv</varname> (<emphasis role="strong">y no</emphasis> el número de argumentos pasados a su script).

</para>

<para>

Mientras los argumentos pasados al script no comiencen con el carácter <literal>-</literal>, no hay nada especial que vigilar. El hecho de pasar argumentos al script que comienzan con <literal>-</literal> plantea problemas porque PHP pensará que debe interpretarlos. Para evitar esto, use el separador <literal>--</literal>. Después de este argumento, todos los argumentos siguientes se pasarán al script sin ser modificados ni analizados por PHP.

</para>

<informalexample>

<screen>

<![CDATA[

# Esto no ejecutará el código, sino que mostrará la ayuda de PHP

$ php -r 'var_dump($argv);' -h

Uso: php [opciones] [-f] <archivo> [args...]

[...]

# Esto pasará el argumento '-h' al script y evitará que PHP lo maneje

$ php -r 'var_dump($argv);' -- -h

array(2) {

[0]=>

string(1) "-"

[1]=>

string(2) "-h"

}

]]>

</screen>

</informalexample>

<para>

Sin embargo, hay otra forma de usar PHP como script shell; la primera línea del script debe ser <literal>#!/usr/bin/php</literal> (a reemplazar por la ruta hacia el binario PHP &cli; en el sistema subyacente). El resto del archivo debe contener el código PHP normal, comprendido entre las etiquetas de apertura/cierre. Después de establecer los permisos de ejecución en el script (<command>chmod +x test</command>), puede ejecutarse como un script shell o perl habitual:

</para>

<example>

<title>Ejecuta un script PHP como script shell</title>

<programlisting role="php">

<![CDATA[

#!/usr/bin/php

<?php

var_dump($argv);

?>

]]>

</programlisting>

<para>

Suponiendo que este archivo se llame <filename>test</filename>, en el directorio actual, entonces es posible hacer esto:

</para>

<screen>

<![CDATA[

$ chmod +x test

$ ./test -h -- foo

array(4) {

[0]=>

string(6) "./test"

[1]=>

string(2) "-h"

[2]=>

string(2) "--"

[3]=>