spunQ_Process Class Reference

Interface to external applications. More...

List of all members.

Public Member Functions

__construct ($executable, $parameters)

Constructor.

write ($string, $finished)

Writes a string into the stdin of the process.

readStdout ()

Reads output of the process.

read ()

Alias for readStdout().

readStderr ()

Reads the error pipe of this applications.

terminate ()

Closes all open pipes and terminates the process.

Static Public Member Functions

static callExternalApplication ($executable, $parameters=array())

Basic way to call an external application.

Protected Member Functions

readPipe ($pipe, $throwException)

Reads from specified pipe.

Static Protected Member Functions

static createCommand ($executable, $parameters=array())

Convenience function that will create a shell command for an executable.

Protected Attributes

$executable

The name of the executable being called.

$parameters

Parameters to the executable.

$process

The process resource provided by PHP.

$pipes

Communication pipes.

$stderrBuffer = ''

A buffer containing unprocessed output of stderr.

Detailed Description

Interface to external applications.

All names of executables used in this class can be configured in the spunQ configuration. If on needs the application ps, for example, the spunQ configuration value spunQ.externalApplications.ps will be used as the application name, if one was provided. The executable is assumed to bed in the PATH if no such value is configured.
The static function callExternalApplication() should be completely sufficient in most cases. Instantiate this class only if you have a complex data flow with the process. Example using the bc calculator:

   try {
     $process = new spunQ_Process('bc', array('-sq'));
     $process->write('1+2*sqrt(16)', false);
     echo $process->readStdout(); // prints 9
     $process->write('1+2*sqrt(9)', true);
     echo $process->readStdout(); // prints 7
     $process->terminate();
   } catch (spunQ_ExternalApplicationFailureException $e) {
     // handle exception
   }

Note that calling external applications is always hard to setup, debug and maintain, avoid it whenever you can!

Definition at line 28 of file Process.class.php.

Constructor & Destructor Documentation

spunQ_Process::__construct	(	$	executable,
		$	parameters
	)

Constructor.

Parameters:

	$executable	The name of the executable.
	$parameters	Parameters to pass to the executable.

Exceptions:

spunQ_ExternalApplicationFailureException

Definition at line 107 of file Process.class.php.

Member Function Documentation

static spunQ_Process::callExternalApplication	(	$	executable,
		$	parameters = `array()`
	)			`[static]`

Basic way to call an external application.

Parameters:

	$executable	The name of the executable.
	$parameters	Parameters to pass to the executable.

Returns:: array<string> Output of the process, buffered line by line without trailing newlines. So, implode("\n", $returnValue) will reconstruct the output string.

Exceptions:

spunQ_ExternalApplicationFailureException

Definition at line 40 of file Process.class.php.

static spunQ_Process::createCommand	(	$	executable,
		$	parameters = `array()`
	)			`[static, protected]`

Convenience function that will create a shell command for an executable.

Parameters:

	$executable	The name of the executable.
	$parameters	Parameters to pass to the executable.

Returns:: string It is safe to pass the resulting string to exec() or similar. NOTE: 'safe' means that the command will be called with the given arguments. Using external applications is still prone to many attack vectors.

Definition at line 60 of file Process.class.php.

spunQ_Process::readPipe	(	$	pipe,
		$	throwException
	)			`[protected]`

Reads from specified pipe.

This function will block until there is something to read.

Parameters:

	$pipe	The pipe to read from
	$throwException	Whether to throw exceptions in case of an error.

Returns:: string The string that was read.

Definition at line 196 of file Process.class.php.

spunQ_Process::readStderr ( )

Reads the error pipe of this applications.

Returns:: string

Definition at line 168 of file Process.class.php.

spunQ_Process::readStdout ( )

Reads output of the process.

Returns:: string

Exceptions:

spunQ_ExternalApplicationFailureException

Definition at line 153 of file Process.class.php.

spunQ_Process::terminate ( )

Closes all open pipes and terminates the process.

Returns:: integer The return code of the process.

Definition at line 179 of file Process.class.php.

spunQ_Process::write	(	$	string,
		$	finished
	)

Writes a string into the stdin of the process.

Parameters:

	$string	The string to write.
	$finished	Whether there will be no more write operations on this process. If this is set to true, the stdin pipe will be closed. This is necessary for many executables to start operation.

Returns:: spunQ_Process $this

Exceptions:

spunQ_ExternalApplicationFailureException

Definition at line 132 of file Process.class.php.

Member Data Documentation

spunQ_Process::$executable [protected]

The name of the executable being called.

Type:: string

Definition at line 69 of file Process.class.php.

spunQ_Process::$parameters [protected]

Parameters to the executable.

Type:: array<string>

Definition at line 75 of file Process.class.php.

spunQ_Process::$pipes [protected]

Communication pipes.

These contain stdin[0], stdout[1] and stderr[2] pipes to the process at given indexes. Any closed pipe will be replaced by NULL.

Type:: array<resource>

Definition at line 89 of file Process.class.php.

spunQ_Process::$process [protected]

The process resource provided by PHP.

Type:: resource

Definition at line 81 of file Process.class.php.

spunQ_Process::$stderrBuffer = '' [protected]

A buffer containing unprocessed output of stderr.

The class tries to provide hints as to why an operation failed and will read the stderr pipe arbitrarily. In order to be able to provide the contents on demand, they will be buffered here. Have a look at the implementation of write() and readStderr(), if this confuses you.

Type:: string

Definition at line 99 of file Process.class.php.

The documentation for this class was generated from the following file:

Process.class.php


Public Member Functions
	__construct ($executable, $parameters)
	Constructor.
	write ($string, $finished)
	Writes a string into the stdin of the process.
	readStdout ()
	Reads output of the process.
	read ()
	Alias for readStdout().
	readStderr ()
	Reads the error pipe of this applications.
	terminate ()
	Closes all open pipes and terminates the process.
Static Public Member Functions
static	callExternalApplication ($executable, $parameters=array())
	Basic way to call an external application.
Protected Member Functions
	readPipe ($pipe, $throwException)
	Reads from specified pipe.
Static Protected Member Functions
static	createCommand ($executable, $parameters=array())
	Convenience function that will create a shell command for an executable.
Protected Attributes
	$executable
	The name of the executable being called.
	$parameters
	Parameters to the executable.
	$process
	The process resource provided by PHP.
	$pipes
	Communication pipes.
	$stderrBuffer = ''
	A buffer containing unprocessed output of stderr.