<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Executing PHP files</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="features.commandline.options.html">Options</a></div>
<div class="next" style="text-align: right; float: right;"><a href="features.commandline.io-streams.html">I/O streams</a></div>
<div class="up"><a href="features.commandline.html">Command line usage</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="features.commandline.usage" class="section">
<h2 class="title">Executing PHP files</h2>
<p class="para">
There are three different ways of supplying the <acronym title="Command Line Interpreter/Interface">CLI</acronym> <acronym title="Server Application Programming Interface">SAPI</acronym> with PHP code
to be executed:
<ol type="1">
<li class="listitem">
<p class="para">
Tell PHP to execute a certain file.
</p>
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
$ php my_script.php
$ php -f my_script.php
</pre></div>
</div>
</div>
<p class="para">
Both ways (whether using the <strong class="option unknown">-f</strong>
switch or not) execute
the file <var class="filename">my_script.php</var>. Note that there is no
restriction on which files can be executed; in particular, the filename
is not required have a <em>.php</em> extension.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If arguments need to be passed to the script when using
<strong class="option unknown">-f</strong>
, the first argument must be <em>--</em>.
</p>
</p></blockquote>
</li>
<li class="listitem">
<p class="para">
Pass the PHP code to execute directly on the command line.
</p>
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
$ php -r 'print_r(get_defined_constants());'
</pre></div>
</div>
</div>
<p class="para">
Special care has to be taken with regard to shell variable substitution and
usage of quotes.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Read the example carefully: there are no beginning or ending tags! The
<strong class="option unknown">-r</strong>
switch simply does not need them, and using them will
lead to a parse error.
</p>
</p></blockquote>
</li>
<li class="listitem">
<p class="para">
Provide the PHP code to execute via standard input
(<em>stdin</em>).
</p>
<p class="para">
This gives the powerful ability to create PHP code dynamically and feed it
to the binary, as shown in this (fictional) example:
</p>
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
$ some_application | some_filter | php | sort -u > final_output.txt
</pre></div>
</div>
</div>
</li>
</ol>
You cannot combine any of the three ways to execute code.
</p>
<p class="para">
As with every shell application, the PHP binary accepts a number of
arguments; however, the PHP script can also receive further arguments. The
number of arguments that can be passed to your script is not limited by PHP
(and although the shell has a limit to the number of characters which can be
passed, this is not in general likely to be hit). The arguments passed to
the script are available in the global array <var class="varname"><var class="varname"><a href="reserved.variables.argv.html" class="classname">$argv</a></var></var>. 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 <strong class="option unknown">-r</strong>
, the value of <var class="varname"><var class="varname"><a href="reserved.variables.argv.html" class="classname">$argv[0]</a></var></var>
will be just a dash (<em>-</em>). The same is true if the code is
executed via a pipe from <em>STDIN</em>.
</p>
<p class="para">
A second global variable, <var class="varname"><var class="varname"><a href="reserved.variables.argc.html" class="classname">$argc</a></var></var>,
contains the number of elements in the <var class="varname"><var class="varname"><a href="reserved.variables.argv.html" class="classname">$argv</a></var></var> array
(<em class="emphasis">not</em> the number of arguments passed to the
script).
</p>
<p class="para">
As long as the arguments to be passed to the script do not start with
the <em>-</em> character, there's nothing special to watch out for.
Passing an argument to the script which starts with a <em>-</em>
will cause trouble because the PHP interpreter thinks it has to handle it
itself, even before executing the script. To prevent this, use the argument
list separator <em>--</em>. After this separator has been parsed by
PHP, every following argument is passed untouched to the script.
</p>
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]
# This will pass the '-h' argument to the script and prevent PHP from showing its usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
}
</pre></div>
</div>
</div>
<p class="para">
However, on Unix systems there's another way of using PHP for shell
scripting: make the first line of the script start with
<em>#!/usr/bin/php</em> (or whatever the path to your PHP <acronym title="Command Line Interpreter/Interface">CLI</acronym>
binary is if different). The rest of the file should contain normal PHP code
within the usual PHP starting and end tags. Once the execution attributes of
the file are set appropriately (e.g. <strong class="command">chmod +x test</strong>),
the script can be executed like any other shell or perl script:
</p>
<div class="example" id="example-375">
<p><strong>Example #1 Execute PHP script as shell script</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
#!/usr/bin/php<br /><span style="color: #0000BB"><?php<br />var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$argv</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
Assuming this file is named <var class="filename">test</var> in the current
directory, it is now possible to do the following:
</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
$ chmod +x test
$ ./test -h -- foo
array(4) {
[0]=>
string(6) "./test"
[1]=>
string(2) "-h"
[2]=>
string(2) "--"
[3]=>
string(3) "foo"
}
</pre></div>
</div>
</div>
<p class="para">
As can be seen, in this case no special care needs to be taken when passing parameters
starting with <em>-</em>.
</p>
<p class="para">
The PHP executable can be used to run PHP scripts absolutely independent of
the web server. On Unix systems, the special <em>#!</em> (or
"shebang") first line should be added to PHP scripts so that the system can
automatically tell which program should run the script. On Windows platforms,
it's possible to associate <var class="filename">php.exe</var> with the double
click option of the <em>.php</em> extension, or a batch file can
be created to run scripts through PHP. The special shebang first line for
Unix does no harm on Windows (as it's formatted as a PHP comment), so cross
platform programs can be written by including it. A simple example of
writing a command line PHP program is shown below.
</p>
<p class="para">
<div class="example" id="example-376">
<p><strong>Example #2 Script intended to be run from command line (script.php)</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
#!/usr/bin/php<br /><span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">if (</span><span style="color: #0000BB">$argc </span><span style="color: #007700">!= </span><span style="color: #0000BB">2 </span><span style="color: #007700">|| </span><span style="color: #0000BB">in_array</span><span style="color: #007700">(</span><span style="color: #0000BB">$argv</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">], array(</span><span style="color: #DD0000">'--help'</span><span style="color: #007700">, </span><span style="color: #DD0000">'-help'</span><span style="color: #007700">, </span><span style="color: #DD0000">'-h'</span><span style="color: #007700">, </span><span style="color: #DD0000">'-?'</span><span style="color: #007700">))) {<br /></span><span style="color: #0000BB">?><br /></span><br />This is a command line PHP script with one option.<br /><br /> Usage:<br /> <span style="color: #0000BB"><?php </span><span style="color: #007700">echo </span><span style="color: #0000BB">$argv</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]; </span><span style="color: #0000BB">?></span> <option><br /><br /> <option> can be some word you would like<br /> to print out. With the --help, -help, -h,<br /> or -? options, you can get this help.<br /><br /><span style="color: #0000BB"><?php<br /></span><span style="color: #007700">} else {<br /> echo </span><span style="color: #0000BB">$argv</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">];<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
The script above includes the Unix shebang first line to indicate that this
file should be run by PHP. We are working with a <acronym title="Command Line Interpreter/Interface">CLI</acronym> version here, so
no <acronym title="Hypertext Transfer Protocol">HTTP</acronym> headers will be output.
</p>
<p class="para">
The program first checks that there is the required one argument (in
addition to the script name, which is also counted). If not, or if the
argument was <strong class="option unknown">--help</strong>
, <strong class="option unknown">-help</strong>
,
<strong class="option unknown">-h</strong>
or <strong class="option unknown">-?</strong>
, the help message is printed out,
using <var class="varname"><var class="varname"><a href="reserved.variables.argv.html" class="classname">$argv[0]</a></var></var> to dynamically print the script name as
typed on the command line. Otherwise, the argument is echoed out exactly as
received.
</p>
<p class="para">
To run the above script on Unix, it must be made
executable, and called simply as <strong class="command">script.php echothis</strong> or
<strong class="command">script.php -h</strong>. On Windows, a batch file similar to the
following can be created for this task:
</p>
<p class="para">
<div class="example" id="example-377">
<p><strong>Example #3 Batch file to run a command line PHP script (script.bat)</strong></p>
<div class="example-contents">
<div class="shellcode"><pre class="shellcode">@echo OFF
"C:\php\php.exe" script.php %*</pre>
</div>
</div>
</div>
</p>
<p class="para">
Assuming the above program is named <var class="filename">script.php</var>, and the
<acronym title="Command Line Interpreter/Interface">CLI</acronym> <var class="filename">php.exe</var> is in <var class="filename">C:\php\php.exe</var>,
this batch file will run it, passing on all appended options:
<strong class="command">script.bat echothis</strong> or <strong class="command">script.bat -h</strong>.
</p>
<p class="para">
See also the <a href="ref.readline.html" class="link">Readline</a> extension
documentation for more functions which can be used to enhance command line
applications in PHP.
</p>
<p class="para">
On Windows, PHP can be configured to run without the need to
supply the <var class="filename">C:\php\php.exe</var> or the <em>.php</em>
extension, as described in <a href="install.windows.commandline.html" class="link">Command
Line PHP on Microsoft Windows</a>.
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="features.commandline.options.html">Options</a></div>
<div class="next" style="text-align: right; float: right;"><a href="features.commandline.io-streams.html">I/O streams</a></div>
<div class="up"><a href="features.commandline.html">Command line usage</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
