Docs For Class CommandLine

Description

Class to provide functions to support external command execution.

This class helps with:

Locating executable program(s).

Building command lines.

Running commands.

Here is an example:

function sudoRm($file) {
// Construct instance and locate 'sudo' and 'rm'
$cl = new CommandLine();
$cl->requirePrograms(array('sudo', 'rm'));
// Construct array of arguments to build command line from.
// IMPORTANT: Always use escapeshellcmd() on dynamic strings.
$args = array($cl->getProgram('sudo'),
$cl->getProgram('rm'),
'-fr',
escapeshellcmd("\"{$file}\""),
'2>&1');
$cmd = $cl->buildCommandLine($args);
}
// Run system command, capture exit code and output
$rc = 0;
$output = array();
exec($cmd, $output, $rc);

see: exec
see: system

Located in /lib/CommandLine.php (line 51)

Method Summary

CommandLine __construct ()

void buildCommandLine (array $args)

true findProgram (string $name, [array $path = null])

void getProgram (string $name)

true requirePrograms (array $names, [array $path = null])

void setProgram (string $name, string $path)

Methods

Constructor __construct (line 61)

Construct a new instance of the CommandLine class.

access: public

CommandLine __construct ()

buildCommandLine (line 240)

Build a entire command line which can be run as a PHP system command.

This method builds a command line from an array of arguments using the following conventions:

The first array entry must be the short name of a program previously registered (we'll look up the full path).

All remaining array entries (if any) are appended to the

command line string (NOTE: Its up to you to decide if escapeshellcmd() function needs to be used on each argument).

For example:

$cl = new CommandLine();
$cl->requirePrograms(array('ls'));
$cmd = $cl->buildCommandLine(array($cl->getProgram('ls'),
'*.txt',
escapeshellcmd('"my file"')));
$last_line = system($cmd, $retval);

access: public

void buildCommandLine (array $args)

array $args: Array of 1 or more elements ([0] is command).

findProgram (line 79)

Locate a executable program.

Searches the default path (/bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin, and /usr/local/sbin). You may include an array of additional directories to search (if included we will search there first).

return: if program found and added to the internal command list.
access: public

true findProgram (string $name, [array $path = null])

string $name: Simple name of program (like: 'ls').
array $path: Optional array of directories to search.

getProgram (line 175)

Get full path to a found program.

This method returns the full path to program which was previously located via one of the 'find' or 'require' invocations. For example:

$cl = new CommandLine();
$cl->findProgram('ls');
$cl->requirePrograms(array('cp', 'rm'));
$ls = $cl->getProgram('ls');
$rm = $cl->getProgram('rm');

access: public

void getProgram (string $name)

string $name: Short name previously used to locate program.

requirePrograms (line 130)

Looks for a set of required executables - exception if ANY are missing.

This function uses the findProgram method to verify that an entire collection of required exectuables are present on the system. If any of the required programs are found to be missing, this function will throw an exception. Example:

$cl = new CommandLine();
$cl->requirePrograms(array('ls', 'bash', 'cp', 'myprog'));

return: if program found and added to the internal command list.
access: public

true requirePrograms (array $names, [array $path = null])

array $names: Array of program names.
array $path: Optional array of directories to search.

setProgram (line 201)

Add a registered program into the collection.

This method adds (or replaces) a program into the collection. For example:

$cl = new CommandLine();
$cl->setProgram('myscript','/home/pkb/bin/myscript');

access: public

void setProgram (string $name, string $path)

string $name: Short name to register the program under.
string $path: The fully qualified path.