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.

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.

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

• En esta clase de CGI SAPI no hay cabeceras ("headers") escritas en el resultado ("output").

  Aunque el CGI SAPI provee una manera de suprimir HTTP cabeceras ("headers"), no existe una opci贸n equivalente que los activa en el CLI SAPI.

  CLI autom谩ticamente empieza en modo silencioso, la opci贸n -q existe por compatibilidad con antiguos programas CGI.

  No cambia el directorio corriente, a ese en el cual el programa vive. La opci贸n -C es mantenida por compatibilidad.

  Errores son reportados en texto, no en el formato HTML.

• Hay ciertas directivas en el php.ini que son sobrescrita por el CLI SAPI por que estas no hacen mucho sentido en situaciones donde la l铆nea de comando es usada:

  Tabla 43-1. Directivas sobrescrita en php.ini

  Directivas (directives)	CLI SAPI evalu贸 autom谩tico (default value)	Commentario (comment)
  html_errors	FALSE	Cuando los resultados incorrectos aparecen en tu l铆nea de comando, puede ser dif铆cil hacer sentido de ellos con todas esas HTML tags, por esta raz贸n, esta directiva es autom谩ticamente FALSE.
  implicit_flush	TRUE	Es deseoso que los resultados de print (imprimir)(), echo (ecco)() y otras relacionadas, sean inmediatamente escritas como resultados y no mantenidas en ning煤n buffer. Tu todav铆a puedes usar output buffering si tu quieres manipular los resultados proveidos autom谩ticamente.
  max_execution_time	0 (unlimited)	Debido un numero ilimitado de posibilidades de usar PHP en la l铆nea de comando, el m谩ximo tiempo de ejecuci贸n es ilimitado. Aunque aplicaciones escritas para el Internet, usualmente requieres una r谩pida ejecuci贸n, la clase de aplicaci贸n que es ejecutada desde la l铆nea de comando, usualmente necesitan mas tiempo para ejecutar correctamente.
  register_argc_argv	TRUE	Por que estas opciones son TRUE tu siempre necesitaras acceso al argc (el numero de argumentos pasados a la aplicaci贸n) y argv (el array de argumentos) en el CLI SAPI. Desde la versi贸n 4.3.0 de PHP, las variables $argc y $argv son registradas y llenadas con los resultados apropiados cuando usando CLI SAPI. Antes de esta versi贸n, la creaci贸n de estas variables es similar a como en CGI y MODULE versiones que requiere la PHP directiva register_globals estar on (active). Sin importar la versi贸n o la configuraci贸n de register_globals tu siempre puedes trabajar por medio de $_SERVER o $HTTP_SERVER_VARS. Por ejemplo: $_SERVER['argv']

  Nota: Estas instrucciones no pueden ser iniciadas con valores que son diferentes a los de la configuraci贸n en php.ini o el archivo correspondiente. Esta es una limitaci贸n dada por que esos valores autom谩ticos, son aplicados despu茅s de que todos los archivos conteniendo par谩metros de configuraci贸n an sido ejecutados; PERO, esto valores pueden ser cambiados mientras to programa esta ejecutando (esto no hace sentido para todas las directivas, como por ejemplo register_argc_argv).

• Para facilitar trabajando en la l铆nea de comando, las siguientes constantes son definidas:

  Tabla 43-2. constantes especificas de CLI

  Constant (constante)	Description (descripci贸n)
  STDIN	Una stream abierta hacia stdin. Esto nos salva de abrirla con $stdin = fopen('php://stdin', 'r');
  STDOUT	Una stream abierta hacia stdout. Esto nos salva de abrirla con $stdout = fopen('php://stdout', 'w');
  STDERR	Una stream abierta hacia stderr. Esto nos salva de abrirla con $stderr = fopen('php://stderr', 'w');

  Dado lo anterior, tu no necesitas abrir, como por ejemplo, una stream hacia stderr manualmente, solamente necesitas usar la constante en vez de usar los recursos de la stream:

  php -r 'fwrite(STDERR, "stderr\n");'

  No necesitas cerrar estas stream expl铆citamente, desde que son cerradas autom谩ticamente por PHP cuando tu programa termina.

• El CLI SAPI no cambia el directorio en el cual to estas corrientemente, al directorio donde el programa ejecutado vive!

  Ejemplo mostrando la diferencia al CGI SAPI:

  <?php     /* Nuestra aplicaci&oacute;n llamada.php*/     echo getcwd(), "\n"; ?>

  Cuando usas la versi贸n CGI el resultado es:

  $ pwd /tmp $ php -q otro_directorio/test.php /tmp/otro_directorio

  Esto claramente muestra que PHP cambia su directorio al usado por el programa que ejecutas.

  Usando el CLI SAPI resulta:

  $ pwd /tmp $ php -f otro_directorio/test.php /tmp

  Esto no da mas flexibilidad cuando escribiendo utilidades en la l铆nea de comando con PHP.

  Nota:

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

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

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:

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:

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