Capítulo 23_ 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 23_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 23_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:

#!/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:

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