CLI SAPI differences

In many ways, the CLI SAPI works in the same way as the CGI SAPI and other SAPIs. However, it is important to keep track of where it differs and why, because it will directly affect how you write your scripts.

The three easiest to remember differences are that the CLI SAPI does not output headers, does not use HTML formatting for its error messages, and also does not change the working directory to that of the script. The latter is particularly important - when using the CGI SAPI, calling /home/paul/foo.php would set the working directory (where it references files and other objects from) to /home/paul. This is not the same for the CLI SAPI - it uses the location of the CLI SAPI binary as its working directory.

Four php.ini directives are automatically overridden when using the CLI SAPI. These are: html_errors, implicit_flush, max_execution_time, and register_argc_argv. html_errors is set to False by default because, naturally, one is working inside a shell where HTML would only clutter things. implicit_flush is set to True by default. For those unfamiliar with how PHP works, it internally buffers output, sending it to output in chunks. When implicit_flush is set to True , PHP sends any output from print, echo, etc, straight to output without trying to buffer it. In PHP's normal operating environment, the web, this can slow things down tremendously, and is generally not advised. However, it would not be very helpful for PHP to buffer things when the output is a shell, because users want their feedback immediately. As such, implicit_flush defaults to False for the CLI SAPI.

Owing to the fact that shell scripts can run for much longer than web scripts, max_execution_time defaults to 0 for the CLI SAPI. This allows your shell scripts to have an infinite execution time. Finally, register_argc_argv is automatically set to True to allow you easy access to argc (the number of arguments passed to your script) and argv (an array of the arguments themselves).

The final key difference between the CLI SAPI and other SAPIs is that the CLI SAPI automatically sets the constants STDIN, STDOUT, and STDERR for you, simply because you are likely to be working with at least one of these three fairly regularly. These are common terms in the Unix world, but if you're on Windows it might be the first time you've heard them. Put simply, each process (program) has a place where it can write its output, accept input, and print errors. By default these are all the terminal that launched the program, but they can be redirected so that, for example, one programs STDIN (input) might read from another's STDOUT (output), thereby chaining them together.

As the CLI SAPI is designed to work with the terminal, these three streams are opened for you as constants so you have easy access to them.

Also, it is important to note that there are two ways you can execute your PHP scripts. The first way is to use php -f /path/to/yourfile.php - this simply calls the binary and passes your script as a parameter and is a little clumsy, if effective. My preferred manner is to chmod +x PHP files I wish to call from a shell, then add an appropriate shebang line at the top, something like this: #!/usr/local/bin/php.


Want to learn PHP 7?

Hacking with PHP has been fully updated for PHP 7, and is now available as a downloadable PDF. Get over 1200 pages of hands-on PHP learning today!

If this was helpful, please take a moment to tell others about Hacking with PHP by tweeting about it!

Next chapter: Your first CLI script >>

Previous chapter: Why use shell scripts?

Jump to:


Home: Table of Contents

Copyright ©2015 Paul Hudson. Follow me: @twostraws.