11.2. General Shell Scripting Advice
Before I delve into the project I first want to provide some general tips you should keep in mind when writing shell scripts:
Provide usage instructions and help options.
Be sure to provide guidance on how to use your scripts. A good summary of what the script does and its argument list is mandatory if you plan on sharing them with others, but should still be included even if you're the only person who will ever use it. I've written several utility scripts and have come back months later and have forgotten how to use them.
Comment your code.
Writing code to perform common activities solidifies them into procedures and reduces some possibility of human error. Still, just because something is "taken care of" doesn't mean it can be forgotten. Comments can document the steps taken in a human readable format and compliance regulations may require you to comment your code depending on your environment.
Know under which account the script will run.
In general, shell scripts run with the same privileges of the user account that initiated it. This means the script may not be able to change a file's owner or permissions or to perform other activities typically reserved for a super user. You may need to escalate your privileges using su or sudo to run the script.
Command line utilities have a rich tradition and power users have come to expect certain behavior. One such behavior is respecting the use of the standard Unix file descriptors standard-input, standard-output, and standard-error. Competent shell users feel comfortable redirecting and piping the output of one command to the input of another.
PHP automatically opens streams to the standard Unix file descriptors standard-input, standard-output, and standard-error and makes the references available through the magic constants STDIN, STDOUT, and STDERR respectively. PHP also closes these streams automatically as well when the script's execution terminates, saving you the effort of explicitly having to manage these streams yourself with fopen() and fclose().
Because output from an echo or print statement is eventually directed to STDOUT, you will most likely never have to direct it to that stream yourself. You may find STDIN more useful, however, since it is used to read in user input from a prompt. It's a good idea to send error messages to STDERR, separate from output sent to STDOUT. This allows the developer running the script to send error messages to a separate file using redirection for later review, like this:
$ ./startproject -o /srv/apache/example.com/test 2>errors.txt
Supply default values for prompts when appropriate.
Providing default values for a prompt offers the user guidance as to what type of information the script expects. If the value applies to the current project, then the developer has to type less and has a lesser chance of entering a typo. This all helps to make the script easier to use.
Validate user input.
Input should be properly validated and escaped regardless if the execution of a script is initiated at the command line or a web request. Never trust user input—people can (and will) provide all sorts of crazy and unexpected input. Sometimes this is accidental but other times it's malicious. Malformed input could be potentially even more dangerous for a shell script than a web page depending on the code's activities.
Write code with portability in mind.
Unless the script only performs a platform-specific function, don't expect it to be used only on just one particular platform. You might develop it on Unix, but people you share the script with run it on Windows. Or perhaps you write it on AIX and then the production server migrates to Novel. Use PHP functions when they are available and avoid using exec(), passthru(), and system().