cliApplication

Provides the necessary infra-structure to run a CLI application. This includes command chaining, listeners for handling application events during runtime, signal handling and more.

cliApplication can be extended for different application types as is the case with cliDaemon, however it does not need to be as all the commands are specified at runtime by creating a command chain for the current application. In this manner you can swap and change individual commands in any application.

Some commands are shared e.g. help, new, logging etc. this means all you have to do is build your specific commands for your app. The application associates itself with the cliRequest so you can always access the base application context during execution.

cliApplication allows listeners to be attached and notified during execution. A specific cliApplicationEvent can be created and dispatched to the listeners.

// a really basic example of an app in /temp called test.php
require_once(dirname(dirname(__FILE__)).DIRECTORY_SEPARATOR.'libraries'.DIRECTORY_SEPARATOR.'system.inc');

$oApp = new cliApplication('testApp', 'This is a test CLI application to see if the ideas will work');
$oRequest = cliRequest::getInstance()->setApplication($oApp);
$oApp->getCommandChain()
	->addCommand(new cliCommandLog($oRequest))
	->addCommand(new cliCommandLogToConsole($oRequest))
	->addCommand(new cliCommandHelp($oRequest))
);

// to add signal interception - your command will have to check signals
// by using: if ( $this->getRequest()->getApplication()->signalTrapped() )
// $oApp->trapSignal(SIGINT, SIGHUP, SIGTERM);
$oApp->execute($oRequest);

Note: the command chain ORDER is very important with respect to parameters (arguments). Switches are always processed first, followed by commands. The first matching command is executed by cliApplication after which it is up to the commands to re-route to additional logic. If left alone, cliApplication terminates after the first argument is matched and fired.

Note 2: execute() is wrapped in a try {} catch {} set but will only capture cliApplicationCommandExceptions thrown from the commands. This information will be pretty printed (to a point) on the command line. The exception trace can be obtained by adding the switch -V to enable very verbose mode, but only if the help command is in the current command chain.


Methods

public __construct([$inAppName = null], [$inAppDescription = null], [$inCliResponse = null])

Creates a new cliApplication instance

public execute($inRequest)

Executes the application stack

protected _formatException($inException, $inRequest)

Formats an exception to be displayed on the CLI terminal

public notify($inEvent)

Fires a notification to any attached listeners on the application

public registerCommandPath([$inPath = null])

Registers a path with the autoloader that additional commands can be located in

Note: this method has difficulty resolving applications running under Cygwin. In these cases, you should set this path explicitly from your scriptname.php file, rather than trying to rely on the system derived script path.

public reset()

Resets the object

public isModified()

Returns true if object has been modified

public setModified([$inStatus = true])

Set $_Modified to $inStatus

public getApplicationName()

Returns $_ApplicationName

public setApplicationName($inApplicationName)

Set $_ApplicationName to $inApplicationName

public getApplicationDescription()

Returns $_ApplicationDescription

public setApplicationDescription($inApplicationDescription)

Set $_ApplicationDescription to $inApplicationDescription

public getResponse()

Returns $_Response

public setResponse($inResponse)

Set $_Response to $inResponse

public getCommandChain()

Returns the application command chain

public getListeners()

Returns the application listeners object

public isRegisteredSignal($inSignal)

Returns true if $inSignal has been registered with the signal handler

public trapSignal()

Registers a set of signals to be intercepted and handled by the application.

Multiple signals can be passed in as arguments. The PHP constants SIG* should be used when specifying the signals.

// example of trapping various signals
$oApp = new cliApplication('app', 'description');
$oApp->trapSignal(SIGCHLD, SIGINT, SIGTERM ...);

public signalTrapped([$inSignal = false])

Checks if any or a specific signal has been caught by the signalHandler.

Returns the number of signals caught. The signal count depends on which signals are being handled by the application. If none are registered, this will always return 0.

public signalHandler($inSignal)

Signal handler, records $inSignal in the internal array of caught signals.

The signals to be handled by the application are registered using cliApplication::trapSignal(). When a signal is intercepted by the signal handler, it is checked to see if it is an application controlled signal. It is, the event is logged and it is up to the application to detect and handle the signal via cliApplication::signalTrapped().

Any unhandled signals (including kill -9) will cause immediate termination of the process - possibly resulting in un-predictable behaviour or data corruption.

Note: kill -9 should not be handled. This signal causes immediate application termination, therefore you should avoid using kill -9 daemon/application as it will terminate the process without any chance of the clean-up process firing.

<  1  >