Ejecutando ficheros PHP

Hay tres formas distintas de proveer a la SAPI CLI con código PHP para que sea ejecutado:

1. Decirle a PHP que ejecute un determinado fichero.

   $ php mi_script.php
   
   $ php -f mi_script.php
   

   Ambas formas (usando o no el modificador -f) ejecutan el fichero mi_script.php. Nótese que no hay restricción sobre cuales ficheros puede ser ejecutado; en particular, el nombre del fichero no es necesario que tenga una extensión .php.

   Nota:

   Si se necesita proporcionar argumentos al script, utilizando el modificador -f, el primer argumento debe ser --.

2. Pasar el código PHP para ejecutarlo directamente en la línea de comandos.

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

   Debe tomarse especial cuidado con respecto al uso de comillas y la sustitución de variables de la consola.

   Nota:

   Lea cuidadosamente el ejemplo: No hay etiquetas de inicio y fin. El modificador -r simplemente no lo necesita. Si se usare, provocaría un error sintáctico.

3. Proporcionar el código PHP a ejecutar a través de la entrada estándar (stdin).

   Esto ofrece la posibilidad de crear código PHP dinámicamente para pasárselo al binario, tal y como se ve en este ejemplo (ficticio):

   $ alguna_aplicacion | algun_filtro | php | sort -u > salida_final.txt
   

Como todas las aplicaciones de consola, el binario de PHP acepta un determinado número de argumentos, sin embargo un script PHP también puede recibirlos. El número de argumentos que pueden ser pasados a su script no está limitado por PHP (aunque la consola tiene un determinado número de caracteres límite; usualmente usted no alcanzará este límite). Los argumentos pasados al script están disponibles en el array global $argv. El primer índice (cero) siempre contiene el nombre del script como se llamó desde la línea de comandos. Nótese que, si el código es ejecutado en la línea utilizando el modificador de consola -r, el valor de $argv[0] será simplemente un guión medio -). Lo mismo aplica si el código es ejecutado por medio de una tubería desde la entrada estándar STDIN.

Una segunda variable global, $argc, contiene el número de elementos en el arreglo $argv (pero no el número de argumentos pasados al script).

Dado que los argumentos que se pasan a un script no comienzan con el caracter -, no hay nada especial a tener en cuenta. Si se pasa a un script un argumento que comience por - provocará errores porque el intérprete de PHP pensará que debe manejarlo él, aún antes de ejecutar el script. Para prevenir esto, utilice el separador de lista de argumentos --. Una vez que PHP lea este separador, todos los argumentos que lo sigan se pasarán intactos al script.

# Esto no ejecutará el código dado, sino que mostrará el uso de PHP
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# Esto pasrá el argumento '-h' al script, impidiendo que PHP muestre su uso
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Sin embargo, en sistemas Unix, hay otra forma de usar PHP para scripts de consola. Se puede escribir un script en el que la primera línea comience con #!/usr/bin/php (sustitúyalo por la ruta a su CLI binario de PHP si es diferente). El resto del fichero debería contener código PHP normal con las etiquetas usuales de inicio y fin de PHP. Una vez que se otorguen permisos de ejecución al fichero apropiadamente (p.ej. chmod +x test) el script podrá ejecutarse como cualquier otro script de consola o perl:

$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

Tal y como puede verse, en este caso no hace falta tener cuidado al pasar al script parámetros que comienzan con -.

El ejecutable de PHP puede ser utilizado para ejecutar scripts de PHP que sean absolutamente independientes del servidor web. En sistemas Unix, los caracteres especiales #! (o conocido como "shebang") deben añadirse en la primera línea del script seguido de la ruta hacia el binario de PHP para que le indique autom[aticamente al sistema cual es el programa que debería ejecutar al script. En plataformas Windows puede asociar php.exe para que funcione al hacer doble clic en ficheros con extensión .php, o se puede hacer un fichero por lotes para ejecutar el script mediante PHP. La primera línea especial "shebang" que se añade a un script para que funcione en Unix no interferirá en Windows (ya que está formateado como un comentario de PHP), así que pueden escribirse programas para plataformas independientes incluyéndose sin ningún problema. Más abajo puede encontrarse un ejemplo sencillo de cómo escribir un programa de línea de comandos en PHP.

El script de arriba, incluye la primera línea especial "shebang" de Unix para indicar que este fichero debería ejecutarse por PHP. Puesto que aquí estamos trabajando con una versión CLI, no se mostrarán cabeceras HTTP.

El programa comprueba primero que hay más de un parámetro (adicionalmente al nombre del script, el cual también es contado). Si no lo hay, o si el parámetro fuese --help, -help, -h o -?, se imprime el mensaje de ayuda, utilizando $argv[0] para escribir el nombre del script dinámicamente tal como se escribió en la línea de comandos. De otra manera, el parámetro es mostrado exactamente como se recibió.

Para ejecutar el script superior en Unix, debe otorgarle permisos de ejecución al fichero para hacerlo ejecutable, y llamarlo simplemente como script.php mostrar_esto o script.php -h. En Windows, se puede crear un fichero por lotes para lograr esta tarea:

@echo OFF
"C:\php\php.exe" script.php %*

Asumiendo que el programa superior se llamara script.php, y CLI php.exe estuviera en C:\php\php.exe , este fichero por lotes lo ejecutaría automáticamente con los parámetros que se le hayan pasado: script.bat mostrar_esto o script.bat -h.

Vea también la documentación de extensión Readline para conocer más funciones que pueden ser utilizadas para mejorar las aplicaciones de línea de comandos en PHP.

Si está en Windows, puede configurar PHP para que no sea necesario añadir ni C:\php\php.exe ni la extensión .php, tal como se describe en PHP en Línea de Comandos en Microsoft Windows.