Nicollet.Net

CLI is the command line interface to the PHP interpreter. Instead of running scripts when viewed from the web, this lets PHP run as a standard shell scripting language.

Let’s assume that:

• You have a web server running PHP
• You also have command-line access to that server (for instance, the server is running Linux, and you have SSH access).
• The command-line interface is installed (or you can install it or have it installed)

Then you might want to consider using a command-line back-end for your dynamic web site instead of using a web back-end.

What, you think, move back to the prehistoric era of command lines and white-on-black terminals when we have AJAX and Flex?

I certainly don’t deny that command line interfaces are ugly (I pride myself of having a colorful zsh prompt, but that’s about as far as things go), and if you expect non-developers to be administrators then a web administration tool is an absolute necessity.

Still, if the site administrators are all developers (or can be quickly taught how to use the command-line) or if the time to design an interface is short, then command-line interfaces have some advantages.

• No need to secure access to the back-end, since the command-line access to the server is already secure.
• No need to design and debug a complete HTML view, or write and debug javascript to improve a click-based editor.
• You have access to all the typical command-line tools: make/sed/cron/grep/awk/sort/…, shell scripting, loading data from files, and all other automation tools that can improve administration speed.
• The administration tool runs with your user rights, not the web server rights, meaning you can increase the paranoia of the web server rights without restricting the capabilities administration tool.
• You can even invoke external tools that have no point being part of the web site, which serve development purposes (such as diagnosis tools or optimization tools).

How-to

On your typical debian-based LAMP stack, installing the CLI is as easy as an apt-get install php5-cli (or the equivalent for your distribution). Running a PHP program on the command line is done with php5 script.php — arg1 arg2. Anything the script outputs is printed to the output stream, and the arguments are available as the global variable $argv.

For instance, a sample script that takes a single argument and outputs that argument squared would be written as:

<?php echo $argv[1] * $argv[1]; ?>

Additional details are of course best read from the PHP documentation itself.

Tips and tricks

• Mind your relative paths. Usually, the administration scripts will want to behave as if they were part of the web server, which means that the appropriate paths must be added to the path. A good idea is to share configuration files between the administration scripts and the web site itself, and choose a root path from where all relative paths should be handled (the script should then cd to that root path before doing anything else).

• Provide shell-friendly data. This involves placing one row of data per line, and using a common separator (such as a colon) between fields. Non-data lines can be used, but it is best if they are prefixed with a comment symbol, such as # or –. If only one piece of data is required, provide it with no other decoration (except whitespace) so that it can be used as a shell variable.

• Make everything transactional. This is usually a no-brainer, but it’s easy to forget. When a set of operations must be performed, either check beforehand that all of them will be done without error, or use a transaction system to avoid failing in the middle of a database or filesystem modification.

• Include a help page. You will inevitably forget how to use certain commands. A general help page (display the list of commands with a summary of their usage) and specific help pages for every non-trivial command are always useful later on.

• Rely on PHP introspection. PHP can determine if an object has a certain member, so scripts which can support several operations (such as create/view/list/edit) can be turned into objects with the appropriate members.

• Use CRUD if your underlying model allows it. The typical manipulations performed by an administrator are the creation, retrieval,modification and deletion of individual pieces of data from the persisten model. Also be ready to provide complete lists of elements with relevant information, but don’t reimplement wheels such as searching by e-mail (grep) or sorting by age (sort).

• Log everything. You can write to a file every command that is executed using a script. Incorporate a logging system which prints out the current date, the script arguments, and interesting environment variables (for instance, the current user).

• Standardize argument retrieval. For instance, if the script user writes makeuser -name foo -pass bar, then the script should be able to access the arguments as array( “name” => “foo”, “pass” => “bar” ) and not as array(“makeuser”, “-name”, “foo”, “-pass”, “bar”).

• Standardize column printing. For instance, if you need to print data as columns of fixed widths, separated by colons, it should be written as $printer = new Printer(5,10,10,50,10); $printer -> print($id, $created, $label, $content, $hits); and not anything more complex. Don’t mix content and formatting.

• You’re safe, so take advantage of it. Disable running the scripts as CGI (meaning they can only be run with access to the local machine from the appropriate user groups) and feel free to display any useful data. If your application is directory-driven (it could be using the Zend Framework) apply glob() all over the place to display a clean diagnosis of what the application can use or find.

A little warning

Don’t get overzealous. While it may be interesting to control every single aspect of the web site from the command line, reinventing common wheels (such as database backups or version control) will take more time than it’s worth, and safety must be a constant concern in order to prevent executing any administration script from the web.

Also avoid creating non-elementary operations. These are ultimately best implemented as shell scripts (in the language of your choice, including PHP) that exist outside the application and only interact with the application through the administration tools, thereby saving you the time wasted on reimplementation and security checks.