PHP asynchronous execution framework
------------------------------------

This framework allows you to execute asynchronously arbitrary shell command from
PHP process. It features the following functionality:
* open file descriptors for communication between the PHP process and the child
  one. Right now we support reading child's STDOUT and STDERR.
* ability to query whether the child process has finished its execution
* query PID of the child process, possibly for sending signals to it
* read exit code of the child process once it has finished its execution
* pre-inclined for easy caching of the child process results

------------------
Examples of usage:
------------------

Most simple asynchronous execution:
-----------------------------------
<?php
$command = 'my-command';
$args = array();
$args[] = array(
  'key' => '--name-of-the-argument',
  'glue' => ' ',
  'value' => 'value of the argument',
);

$child = new ToolsAsyncResult($cmd, $args);

// Your 'my-command --name-of-the-argument "value of the argument"' is being
// executed right now. In the mean time you can do something useful in your main
// PHP process.
do_something_useful();

// When you decide you need the results of asynchronous child process, simply do
// the following. If the command has not finished yet, your main PHP process
// will sleep until the execution is finished.
$result = $child->result();

if ($result['exit'] != 0) {
  // Whoups... The child process did not terminate with exit code 0.
  // Let's see, maybe there is more hints about what went wrong in the STDERR.
  $stderr = $result['stderr'];
}

// Now let's save the STDOUT from the child process somewhere.
$stdout = $result['stdout'];
?>

Run the asynchronous command and query whether it has finished:
---------------------------------------------------------------
<?php
$command = 'my-command';
$args = array();
$args[] = array(
  'key' => '--name-of-the-argument',
  'glue' => ' ',
  'value' => 'value of the argument',
);

$child = new ToolsAsyncResult($cmd, $args);

// While the child process is running, and as we do not want to sleep in the
// main PHP process waiting for the results, let's keep doing something useful.
while ($child->isRunning()) {
  do_something_useful();
}

// Now we fetched the child process results without actually sleeping a second
// in the main PHP process.
$result = $child->result();

?>

Additional file descriptors passed to your asynchronous command:
----------------------------------------------------------------
<?php
$command = 'my-awesome-command';
$args = array();

// Sometimes your command will communicate on more file descriptors than just
// STDOUT & STDERR. So you can provide additional file descriptors to your child
// command, be it a pipe or an actual file.
// See http://php.net/manual/en/function.proc-open.php for full list of
// available options.
$extra_descriptors = array(
  4 => array('pipe', 'w'),
);

$result = new ToolsAsyncResult($cmd, $args, NULL, array(), $extra_descriptors)->result();

// Let's see what our child command has communicated on the 4th file descriptor.
$fd4 = $result['streams'][4];
?>


Example of synchronous caching:
-------------------------------
<?php

/**
 * This function simply encapsulate starting a child process asynchronously.
 *
 * But let's put a bit on top of it. Before we take off to create a child
 * process, let's check if the results of $cmd are not available in cache. If
 * they are available, we return them right away without bothering with the
 * whole thing of asynchronous command.
 * Also, when the asynchronous command finishes execution, we take a note of its
 * result and if it's positive (exit code equals 0) we store it in the cache
 * bin. That way we guarantee asynchronous command will be only initiated for
 * commands that have not been run before.
 */
function do_something_asynchronously($cmd) {
  $cache = cache_bin_get($cmd);
  if ($cache) {
    // ToolsResult class has identical methods as the ToolsAsyncResult does,
    // but this one does not execute any asynchronous command, but simply stores
    // the $cache result until it is requested at some later point. That way we
    // can freely swap between ToolsResult and ToolsAsyncResult classes without
    // modifying the rest of our code.
    return new ToolsResult($cache);
  }
  return new ToolsAsyncResult($cmd, array(), 'my_process_callback', array($cmd));
}

/**
 * This function plays on par with do_something_asynchronously().
 *
 * When the child process has finished its execution, its results will be passed
 * into this process function before being returned to whoever have requested
 * them. We take the opportunity to store the results of asynchronous command
 * execution into our cache bin so next time they can be fetched much faster
 * from there.
 */
function my_process_callback($info, $cmd) {
  if ($info['exit'] == 0) {
    cache_bin_set($cmd, $info);
  }
  // We could also alter what gets returned to whoever requested the results of
  // asynchronous command execution by just returning something else than $info.
  // But let's keep this example simple.
  return $info;
}

$result = do_something_asynchronously('my-command');
// This line takes to execute as long as the asynchronous command takes to
// execute.
$result->result();

// But if we repeat the same thing over again, our results are already cached
// and this time it happens instantaneously. All you have to do, is to implement
// some cache storage bin.
$result = do_something_asynchronously('my-command');
$result->result();
?>

-----------------
Issues/Questions?
-----------------

Do check the php-async.php file to see full options and features provided by the
framework.