Capítulo 43. Usando PHP desde la línea de comando

Desde la versión 4.3.0, PHP soporta un nuevo tipo de SAPI (Interfaz De Programación De Uso Del Servidor) llamada CLI que significa literalmente interfaz de línea de comando (Command Line Interface). Como el nombre implica, este tipo de SAPI se foca en la creación de aplicaciones que pueden correr desde la línea de comando (o desde el desktop también) con PHP. Hay algunas diferencias dentro del CLI SAPI y otros SAPI que son explicadas en este capítulo. Es importante mencionar que CLI y CGI son diferentes clases de SAPI y comparten algunas características.

La interfaz llamada CLI SAPI fue introducida con PHP 4.2.0, pero es todavía en estado experimental y tiene que ser activada explícitamente con --enable-cli cuando usando ./configure. Desde PHP 4.3.0 la interfaz CLI SAPI es activada automáticamente. Tu puedes usar --disable-cli para de-activarla.

Desde PHP 4.3.0, el nombre, locación, y existencia de los binarios CLI/CGI serán diferentes dependiendo en como Instales PHP en tu sistema. Cuando ejecutes make, CGI, y CLI son compilados automáticamente, y puestas como sapi/cgi/php y sapi/cli/php respectivamente, en el directorio "source" de PHP. Debes notar, que los dos son llamados php. Lo que ocurre durante el proceso make depende en tu línea de configuración (./configure). Si el modulo SAPI es seleccionado durante tu configuración, como por ejemplo apxs, o la opción --disable-cgi es usada, el CLI es copiado a {PREFIX}/bin/php durante la ejecución del comando make install de otras maneras el CGI es instalado aquí. Por ejemplo, si pones --with-apxs en tu configuración, entonces el CLI es copiado a {PREFIX}/bin/php durante make install. Si tu quieres sobrescribir la instalación del CGI binario, utiliza make install-cli después de usar make install. Alternativamente puedes especificar --disable-cgi en tu línea de configuración.

Nota: Por que ambos --enable-cli y --enable-cgi son activados automáticamente, simplemente teniendo --enable-cli en tu línea de configuración no necesariamente significa que CLI son copiados a {PREFIX}/bin/php durante make install.

Los archivos de PHP 4.2.0 y PHP 4.2.3 distribuían el CLI como php-cli.exe, y los mantenía en el mismo directorio que el CGI php.exe. Empezando con PHP 4.3.0 el archivo para windows distribuye el CLI como php.exe en un directorio llamado cli; o sea cli/php.exe.

Que versión de SAPI tengo?: Desde tu línea de comando, ejecutando php -v te dejara saber si php es CGI o CLI.

Diferencias remarcables del CLI SAPI comparadas con otros SAPIs: SAPIs:

Puedes obtener acceso a la lista de opciones proveida por PHP ejecutando PHP con el -hswitch:
Usage: php [options] [-f] <file> [args...]
       php [options] -r <code> [args...]
       php [options] [-- args...]
  -s               Display colour syntax highlighted source.  
  -w               Display source with stripped comments and whitespace.
  -f <file>        Parse <file>.
  -v               Version number
  -c <path>|<file> Look for php.ini file in this directory
  -a               Run interactively
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -z <file>        Load Zend extension <file>.
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -i               PHP information
  -r <code>        Run PHP <code> without using script tags <?..?>
  -h               This help

  args...          Arguments passed to script. Use -- args when first argument 
                   starts with - or script is read from stdin
Aunque los resultados anteriores siempre serán dados en ingles, a continuación te daré una lista que probablemente sera muy útil:
Usage: php [options] [-f] <file> [args...]
         php [options] -r <code> [args...]
         php [options] [-- args...]
    -s               Display colour syntax highlighted source.  
                     (colorear el sintaxis en el c&oacute;digo)
    -w               Display source with stripped comments and whitespace.
                     (remueve los comentarios y espacios del c&oacute;digo) 
    -f <file>        Parse <file>.
                     (analiza <file>)
    -v               Version number
                     (la versi&oacute;n de PHP que estas usando)
    -c <path>|<file> Look for php.ini file in this directory
                     (usa el php.ini archivo localizado aqu&iacute;)
    -a               Run interactively
                     (interactivo)
    -d foo[=bar]     Define INI entry foo with value 'bar'
                     (define foo con el valor 'bar' en php.ini)
    -e               Generate extended information for debugger/profiler
                     (genera mas informaci&oacute;n para el debugger/profiler) 
    -z <file>        Load Zend extension <file>.
                     (inicia las exenciones Zend <archive>)
    -l               Syntax check only (lint)
                     (Mira al sintaxis (lint))
    -m               Show compiled in modules
                     (muestra los m&oacute;dulos compilados)
    -i               PHP information
                     (informaci&oacute;n PHP)
    -r <code>        Run PHP <code> without using script tags <?..?>
                     (ejecuta PHP <code> sin usar las tags <?..?> en el script
    -h               This help
                     (estas opciones)  
    args...          Arguments passed to script. Use -- args when first argument 
                     starts with - or script is read from stdin
                     (Argumentos pasados al programa. Usa -- args cuando el primer 
                     argumento empieza con - o tu programa es le&iacute;do directamente desde stdin)

El CLI SAPI tiene tres diferentes maneras de obtener el código PHP que tu quieres ejecutar:

  1. Puedes decir a PHP que ejecute ciertos archivos.

    php my_script.php
    
    php -f my_script.php
    En estos dos ejemplos (aunque utilices el switch -f o no) ejecutan el archivo my_script.php. Tu puedes escoger cualquier archivo para ejecutar - tus programas PHP no tienen que terminar con la exención .php y pueden tener cualquier otra exención tu desees.

  2. Pasa el código PHP para que sea ejecutado directamente en la línea de comando.

    php -r 'print_r(get_defined_constants());'
    Debes tener cuidado en reguardo a las substituciones variables en tu línea de comando y usando comillas(").

    Nota: Deves ponerle atención al ejemplo, y notaras que no tiene tags ni al principio ni al final, el comando -r simplemente no las usa. Usando las tags te dará un error cuando trates de ejecutar el programa.

  3. Provee el código PHP para ejecutar por medio de stdin

    Esto te da la habilidad de dinámicamente crear código PHP y mandarlo al programa, como por ejemplo a continuación:
    $ some_application | some_filter | php | sort -u >final_output.txt

Tu no puedes combinar ninguna de las tres formas de ejecutar el código.

Como cualquier aplicación ejecutada en la línea de comando, el PHP binario acepta un numero de argumentos y tu programa también puede recibir argumentos. El numero de argumentos que pueden ser pasados a tu programa no es limitado por PHP (la línea de comando tiene limitaciones en el numero de símbolos que pueden ser pasados; usualmente tu nunca alcanzarías este limite). Los argumentos pasados a tu programa, están disponibles en tu array global $argv. El índex cero ("0") siempre contiene el nombre de tu programa (que es - en caso de código que esta viniendo por medio del input estándar, o del switch en la línea de comando -r. La segunda variable global registrada es $argc y contiene el numero de elementos en el array $argv (no el numero de argumentos pasados as programa).

Mientras el argumento que tu quieres pasas a tu programa no comienza con -, no tienes que esperar por nada especial. Pero si el argumento empieza con -, te puede generar problemas, por que PHP pensara que tiene que procesarlo. Para prevenir esto, usa la lista separadora de argumentos: --. Después de que el separador a sido procesado, cada siguiente argumento es pasado sin tocar a tu programa.

# This will not execute the given code but will show the PHP usage
# Esto no ejecutara el c&oacute;digo pero PHP mostrara el uso
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# This will pass the '-h' argument to your script and prevent PHP from showing it's usage
# passaremos el argumento '-h' a tu programa y prevenira que PHP demuestre su uso 
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Pero, existe otra manera de usar PHP en la línea de comando. Tu puedes escribir un programa donde la primera línea empieza con #!/usr/bin/php (donde /usr/bin/php es la locación de php). Después de esto, tu puedes usar PHP común y corriente. Una vez que tu le as dado permiso de ejecución a tu programa (por ejemplo +x test) tu programa puede ser ejecutado como si fuera digamos un programa en perl:
#!/usr/bin/php
<?php
    var_dump
($argv);
?>
Asumiremos que el archivo es llamado test, y esta en el mismo directorio en el cual to estas, en ese caso, podemos hacer lo siguiente.
$ chmod 755 test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}
Como puedes ver, en este caso no atención es dada a pasar los parámetros que comiensen con - en tu programa.

Tabla 43-3. Opciones en la línea de comando

OpcionesDescripcion
-s

colora el sintaxis de tu código

Esta opción usa un mecanismo interno para ejecutar el archivo, y produce una versión coloreada en HML y la escribe como output normal. Nota que todo lo que hace es generar un bloque de <code> [...] </code> HTML tags, no cabecera deHTML es creada.

Nota: Esta opción no trabaja en conjunto con -r.

-w

Te mostrara tu código sin comentarios ni espacios blancos.

Nota: Esta opción no trabaja en conjunto con -r.

-f

Ejecuta el archivo indicado en la opción -f. Esta opción es opcional y puede ser excluida. Solamente proveiendo el archivo que necesita ser ejecutado es suficiente.

-v

Escribe la version de PHP, PHP SAPI y Zend al output normal, por ejemplo:
$ 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

-c

Con esta opción uno puede especificar el directorio donde encontraremos el php.ini archivo, o tu puedes especificar una versión única del mismo (la cual no tiene que ser llamada php.ini), por ejemplo:
$ php -c /costumatisado/directorio/ mi_programa.php

$ php -c /customatisado/directorio/customatisado-archivo.ini mi_programa.php

-a

Corre PHP interactivamente.

-d

Esta opción te hayudara a crear el valor de cualquier directiva de configuración permitidas en el php.ini archivo. El sintaxis es:
-d directiva__de_configuracion [=valor]

Ejemplos:
# Omitting the value part will set the given configuration directive to "1"
# Omitiendo la parte relacionada al valor, le asignara a la directiva de configuracion el valor # "1"
$ php -d max_execution_time -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Passing an empty value part will set the configuration directive to ""
# Pasando un valor vac&iacute;o, le asignara a la directiva de configuraci&oacute;n el valor ""
php -d max_execution_time= -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# The configuration directive will be set to anything passed after the '=' character
# la directiva de configuraci&oacute;n sera asignada a todo pasada el "=" simbolo
$  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"

-e

Generando mas información para el debugger/profiler.

-z

Activa las extensiones Zend. Si solamente un archivo es dado, PHP tratará de activar estas extensiones directamente desde el directorio predeterminado donde esté la biblioteca en su sistema (Usualmente especificado /etc/ld.so.conf en Linux). Pasando el nombre del archivo con descripción absoluta de la ubicación de sus archivos, no usará las bibliotecas en su sistema. Un archivo conteniendo la información de estos directorios, le dira a PHP que solamente trate de activar las extensiones relativas al directorio donde te encuentras

-l

Esta opción proveerá una forma conveniente para marcar tu sintaxis en tu código. En caso de suceso, el texto "No sintax errors detected in <filename> (no errores de sintaxis fueron detectados) es escrito en tu output normal, y la línea de comando retornara el código 0. En caso de problemas, el texto Errors parsing <filename>, en adición al la forma interna de detectar errores, mensajes son escritos como output normal y tu línea de comando recibirá el código 255

Esta opción no encontrara errores fatales (como por ejemplo funciones indefinida), usa -f si tu quieres probar por esta clase de errores también.

Nota: Esta opción no trabaja en conjunción con -r

-m

Usando esta opción, PHP imprime sus módulos internos (y activados) usados por PHP y Zend:
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-i Esta opción llama phpinfo, e imprime los resultado. Si PHP no esta trabajando correctamente, es recomendable que uses esta opción observes si algún mensaje es imprimido antes de, o en medio de la información dada por esta opción. Es un detalle importante que entiendas que el mensaje imprimido es en HTML y por esta razón grandecito.
-r

Esta opción te ayudara a ejecutar PHP directamente desde la línea de comando. Las etiquetas que determinas el principio y al final de tu programa (<?php y ?>) no son necesarias y causaran errores si las pones en tu código.

Nota: Debes tener cuidado cuando usando esta forma de PHP para que no crees conflicto con la substitución de variables usada por la línea de comando.

Ejemplos de errores
$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='
El problema aquí es que sh/bash esta haciendo una substitución de variables, aunque las comillas (") están presentes. Desde que la variable $foo probablemente no esta definida, esta no se inflara en ninguna dirección, el resultado es que el código pasado a PHP para que ejecute realmente lee:
$ php -r " = get_defined_constants();"
La forma correcta de hacer esto, seria usando solamente una comilla ('), variables usando solamente una comilla no son infladas por sh/bash.
$ 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"]=>
  [...]
Si tu no estas usando sh/bash, también puedes encontrar otros problemas. Por favor reporta estos problemas mandando un e-mail a phpdocs@lists.php.net Tu también puedes tener problemas si tratas de poner variables en tu código o cuando usas "/" como símbolos de escape. Te hemos advertido

Nota: -r esta listo en CLI SAPI y no en el CGI SAPI.

-h Con esta opción, tu puedes obtener información acerca de las opciones describías anteriormente, y una breve descripción acerca de sus funciones.

PHP puede ejecutar tus programas absolutamente independiente de tu servidor de páginas de web. Si tu usas Unix, tu puedes añadir una línea especial al principio de tu programa, y hacerlo ejecutable, para que el sistema sepa que programa debe ejecutar tu nueva creación. Si usas windows, tu puedes asociar tu programa con php.exe para que solamente tengas que ejecutarlo como harías con otros programas bajo windows, también puedes crear un "batch" archivo para ejecutar tu programa por medio de PHP. La primera línea que usaste para hacer que tu programa funcione en Unix, no le ara daño a tu programa cuando ejecutad bajo windows, pero de esta manera puedes crear programas que puedes ser usados bajo las dos plataformas. A continuación te daremos un ejemplo:

Ejemplo 43-1. Programa para correr en la línea do comando (script.php)

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

Este es un programa en php entendido para la l&iacute;nea de
comando con una opci&oacute;n.

  Usage:
  <?php echo $argv[0]; ?> <option>

  <option> puede ser cualquier palabra que tu quieras
  imprimir. Con la opci&oacute;n --help, -help -h or -?, tu puedes
  obtener esta informaci&oacute;n

<?php
} else {
    echo
$argv[1];
}
?>

En el programa anterior, usamos una línea especial como nuestra primera línea, para indicar que archivo deber ser ejecutado por PHP. Nosotros trabajamos con una versión de CLI aquí, por eso, no tendremos cabeceras de HTTP imprimidas. Hay dos variables que puedes usar cuando escribiendo aplicaciones en la línea de comando en PHP: $argc y $argv. La primera es el numero de argumentos mas uso (el nombre del programa siendo ejecutado). La segunda es un array conteniendo los argumentos, empezando con el programa nombre, y el numero cero "0" ($argv[0]).

En el programa anterior chequeamos si habían mas, o menos de dos argumentos. También trata de ver si --help, -help, -h o -?, son llamados, e imprime el mensaje de ayuda.

Si tu quieres ejecutar el programa anterior en Unix, tu tienes que hacerlo ejecutable, y simplemente llamado script.php echo this o script.php -h. En windows, tu puedes hacer un batch archivo para alcanzar estos resultados:

Ejemplo 43-2. Archivo batch para ejecutar el programa php (script.bat)

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

Asumiendo que llamaste el programa descrito anteriormente script.php , Y que tienes tu CLI php.exe en c:\php\cli\php.ese este archivo batch, lo ejecutara para ti con las funciones añadidas: script.bat echo this o script.bat -h.

Mira también la documentación de Readline para mas funciones que puedes usar para incrementar tus opciones en este sujeto.

Hosting by: hurra.com
Generated: 2007-01-26 18:00:54