Executing PHP files

The CLISAPI has three different ways of getting the PHP code you want to
execute:

Telling PHP to execute a certain file.

$ php my_script.php
$ php -f my_script.php

Both ways (whether using the -f
switch or not) execute
the file my_script.php. You can choose any file to
execute, and your PHP scripts do not have to end with the
.php extension but can have any name or extension
you wish.

Note:

If you need to pass arguments to your scripts you need to pass
-- as the first argument when using the
-f
switch.

Pass the PHP code to execute directly on the command line.

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

Special care has to be taken in regards of shell variable substitution and
quoting usage.

Note:

Read the example carefully, there are no beginning or ending tags! The
-r
switch simply does not need them. Using them will
lead to a parser error.

Provide the PHP code to execute via standard input
(stdin).

This gives the powerful ability to dynamically create PHP code and feed it
to the binary, as shown in this (fictional) example:

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

You cannot combine any of the three ways to execute code.

Like every shell application, the PHP binary accepts a number of arguments
but your PHP script can also receive arguments. The number of arguments which
can be passed to your script is not limited by PHP (the shell has a certain
size limit in the number of characters which can be passed; usually you won't
hit this limit). The arguments passed to your script are available in the
global array $argv. The first index (zero) always contains the
name of the script as called from the command line. Note that, if the code is
executed in-line using the command line switch -r
, the value of
$argv[0] will be simply a dash (-). The
same is true if the code is executed via a pipe from STDIN.

The second registered global variable is $argc which
contains the number of elements in the $argv array
(not the number of arguments passed to the
script).

As long as the arguments you want to pass to your script do not start with
the - character, there's nothing special to watch out for.
Passing an argument to your script which starts with a -
will cause trouble because PHP itself thinks it has to handle it. To prevent
this, use the argument list separator --. After this
separator has been parsed by PHP, every argument following it is passed
untouched to your script.

However on Unix systems, there's another way of using PHP for shell
scripting. You can write a script where the first line starts with
#!/usr/bin/php (substitute with the path to your PHP CLI
binary if necessary. Following this you can place normal PHP code included
within the PHP starting and end tags. Once you have set the execution
attributes of the file appropriately (e.g. chmod +x test)
your script can be executed like a normal shell or perl script:

Example #1 Execute PHP script as shell script

#!/usr/bin/php<?phpvar_dump($argv);?>

Assuming this file is named test in the current
directory, we can now do the following:

As you see, in this case no care needs to be taken when passing parameters
which start with - to your script.

The PHP executable can be used to run PHP scripts absolutely independent
from the web server. If you are on a Unix system, you should add a special
first line to your PHP script, and make it executable, so the system will
know, what program should run the script. On a Windows platform you can
associate php.exe with the double click option of the
.php files, or you can make a batch
file to run the script through PHP. The first line added to the script to
work on Unix won't hurt on Windows, so you can write cross platform programs
this way. A simple example of writing a command line PHP program can be
found below.

<option> can be some word you would like to print out. With the --help, -help, -h, or -? options, you can get this help.

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

In the script above, we used the special first line to indicate that this
file should be run by PHP. We work with a CLI version here, so there will
be no HTTP header printouts. There are two variables you
can use while writing command line applications with PHP:
$argc and $argv. The first is the
number of arguments plus one (the name of the script running). The second is
an array containing the arguments, starting with the script name as number
zero ($argv[0]).

In the program above we checked if there are less or more than one arguments.
Also if the argument was --help
, -help
,
-h
or -?
, we printed out the help message,
printing the script name dynamically. If we received some other argument we
echoed that out.

If you would like to run the above script on Unix, you need to make it
executable, and simply call it as script.php echothis or
script.php -h. On Windows, you can make a batch file for
this task:

Example #3 Batch file to run a command line PHP script (script.bat)

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

Assuming you named the above program script.php, and you
have your CLIphp.exe in C:\php\php.exe
this batch file will run it for you with your added options:
script.bat echothis or script.bat -h.

See also the Readline extension
documentation for more functions you can use to enhance your command line
applications in PHP.

2. uses "env" to find where PHP is installed: it might be elsewhere in the $PATH, such as /usr/local/bin.

3. if you don't need to use env, you can pass ONE parameter here. For example, to ignore the system's PHP.ini, and go with the defaults, use "-n". (See "man php".)

4. or, you can set exactly one configuration variable. I recommend this one, because display_errors actually takes effect if it is set here. Otherwise, the only place you can enable it is system-wide in php.ini. If you try to use ini_set() in your script itself, it's too late: if your script has a parse error, it will silently die.

5. This will not (as of 2013) work on Linux. It acts as if the whole string, "-n -ddisplay_errors=E_ALL" were a single argument. But in BSD, the shebang line can take more than 2 arguments, and so it may work as intended.

Summary: use (2) for maximum portability, and (4) for maximum debugging.

then PHP will ignore the very first line of your script if it starts with:

#!

So, this line is not only absorbed by the kernel when the script file is executable, but it is also ignored by the PHP engine itself.

However, the engine will NOT ignore the first #! line of any included files withing your "outer" script.php.Any "shebang" line in an included script, will result in simply outputting the line to STDOUT, just as any other text residing outside a <?php ... ?> block.

A gotcha when using #!/usr/bin/php at the start of the file as noted above:

if you originally edited the file on Windows and then attempt to use it on Unix, it won't work because the #! line requires a Unix line ending. Bash gives you the following error message if it has DOS line endings:"bash: /usr/local/bin/wpreplace.php: /usr/bin/php^M: bad interpreter: No such file or directory"

(In Emacs I used "CTRL-X ENTER f" then type "unix" and ENTER to convert)

For Linux and similar, the actual path to php may differ according to the particular distribution's layout. Sometimes it is in /usr/local/bin/php, sometimes /usr/bin/php, and even /home/user/bin/php. So #/usr/bin/php may need to be changed.

But there is an alternative: Use #/usr/bin/env php instead. This uses the environmental setup, and will ordinarily find PHP in one of your $PATH locations, searching down the path to the first hit. (At least I think that's how it works.) If your CLI script will be run in different environments on different machines, this allows it to work without changes. I believe this also works on BSD (which also means MacOS?) but I don't have one around any more to confirm.