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.
Posted by: Scorpio Documentor (Writer), in Cli on 19 Nov 2009 @ 20:30
Tags: cli, cliapplication,
This
work is licenced under a
Creative Commons Licence.