PhpRiot
News Archive
PhpRiot Newsletter
Your Email Address:

More information

PHP Components: Shipping A Command-Line Program

Note: This article was originally published at Planet PHP on 6 April 2011.
Planet PHP

In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I'm going to look at how to go about creating and working with components.

I'm now going under the bonnet of our components, and looking at the different file roles that the PEAR installer expects to find when we distribute our component as a PEAR-compatible package. One of the useful file roles allows us to install new command-line programs (such as PHPUnit, or Phix) onto a computer for everyone to use.

What A Command-Line Program?

A command-line program (the ascript' file role supported by the PEAR installer) is a PHP script that your users run from inside Terminal (or Command on Windows). It allows you to put powerful tools in the hands of your users.

You can also run them as scheduled jobs via cron.

Where Do Command-Line Scripts Go Inside The Component's Structure?

If we take a look at the phix component, you'll find the command-line program itself in the src/bin/ folder:

src/bin/ is meant to be a folder that holds the commands that you want installed into the computer system.

In theory, you could put sub-folders under here, but this is not supported. If you look at phix's actual code, you'll see that the phix command-line program loads code that exists in the src/php/ folder of the component (and is installed into /usr/share/php/ when the PEAR installer installs the component). Your classes should go in src/php/ just like with any other component.

Where Do Command-Line Programs Get Installed?

When you use the PEAR installer to install your component:

$ pear install Gradwell/phix

all of the files in your component's src/bin/ folder gets installed into /usr/bin on your computer:

The command-line script src/bin/phix therefore ends up installed onto your computer as /usr/bin/phix.

The reason why the PEAR installer installs your PHP code under /usr/bin/ is because this folder is normally part of a user's search path in Terminal. That allows users to run your command-line program simply by:

$ phix

without having to specify the full path to your command-line program.

I haven't seen it personally, but there's always the possibility that some Linux distros (and Mac OS X) will install command-line programs into a different folder. You can see where the PEAR installer will put these files on your computer by running:

$ sudo pear config-show | grep bin_dir PEAR executables directory bin_dir /usr/bin

How Do I Make My Command-Line Program Executable?

You're probably used to running PHP scripts from the command line like this:

$ php ./my-script.php

but for command-line programs, you don't want your users having to remember to run everything through the PHP interpreter each time.

UNIX (and UNIX-like operating systems such as Linux) have a long tradition of writing command-line programs using scripting languages. If you put a shebang (the characters #! - hash, pling) at the top of your script, you can tell your operating system how to execute your script.

#!/usr/bin/env php

The line #!/usr/bin/env php tells your operating system to use the PHP CLI interpreter (wherever it is in your Terminal's path) to run this script. Using /usr/bin/env in this way normally makes your script portable across different Linux distros.