Fork me on GitHub

Arara\Process

Build Status
Code Quality
Code Coverage
Latest Version
Total Downloads
License

This library provides a better API to work with processes on Unix-like systems using PHP.

Installation

The package is available on Packagist. You can install it using
Composer.

composer require arara/process

Dependencies

Version 1.6.0 or less of Arara\Process works on PHP 5.3.

Usage

Along with this document, there are many usage examples in the examples/ directory which may be used for reference.

All examples within this document assume you have the following statement at the beginning of the file:

declare(ticks=1);

Without this statement, there is no guarantee PHP will handle signals; this is very important for PCNTL to work properly.
It has been required since version 4.3.0 of PHP, so this is not a request of the library but of the PHP language itself.

If you want to know more about ticks, we recommend you read http://php.net/declare#control-structures.declare.ticks.

Action interface

Forks may be encapsulated using Arara\Process\Action\Action interface.
All classes that implements this interface must implement two methods:

Using this interface you can create your own actions and run them in the background.

Events

The Arara\Process\Action\Action::trigger(..) method, as it is written, associates specific actions with events.
Those events can be:

Callback action

In order to make it easy to execute forks with no need to create a specific class to execute something in the background, there
is a generic implementation that allows a callback to be run in the background; the only thing one must do is pass the callback
to the constructor of this class.

use Arara\Process\Action\Callback;

$callback = new Callback(function () {
    echo "This will be executed in the background!" . PHP_EOL;
});

The Callback action provides a way to bind callbacks to be triggered by specific events:

$callback->bind(Callback::EVENT_SUCCESS, function () {
    echo "This will be executed if the action callback was successful!" . PHP_EOL;
});

Also, one can bind a callback to multiple events:

$callback->bind(Callback::EVENT_ERROR | Callback::EVENT_FAILURE, function () {
    echo "It is going to be executed if the action fails or get an error" . PHP_EOL;
});

Command action

You may want to run just a Linux command, for that reason there is Command action.

$command = new Command('whoami');

Using Command action you can define arguments as second param:

$command = new Command('cp', array('/path/to/source', '/path/to/destination'));

If you prefer arguments can be defined by a key => value array:

$command = new Command(
    'find',
    array(
        '/path/to/dir',
        '-name' => '*',
        '-type' => 'f',
    )
);

Command action is based on Callback action so you can also bind triggers for events.

Daemon action

You can create daemons using the Arara\Process\Action\Daemon class:

$daemon = new Daemon(
    function (Control $control, Context $context, Daemon $daemon) {
        while (! $daemon->isDying()) {
            // Do whatever you want =)
        }
    }
);

This action will:

  1. Detach process session from the parent
  2. Update process umask
  3. Update process work directory
  4. Define process GID (if defined)
  5. Define process UID (if defined)
  6. Recreate standards file descriptors (STDIN, STDOUT and STDERR)
  7. Create Pidfile
  8. Run the defined payload callback

Daemon action is based on Callback action thus you can also bind triggers for events.

Daemon options

Daemon action class has some options that allows you to change some behaviours:

You can change default daemon options by defining it on class constructor:

$daemon = new Daemon(
    $callback,
    array(
        'name' => 'mydaemonname',
        'lock_dir' => __DIR__,
    )
);

After the object is created you may change all options:

$daemon->setOptions(
    array(
        'stdout' => '/tmp/daemon.stdout',
        'stderr' => '/tmp/daemon.stderr',
    )
);

Also you can change just an option:

$daemon->setOption('work_dir', __DIR__);

Starting a process in the background

The class Arara\Process\Child allows you to execute any action in the background.

$child = new Child(
    new Daemon(function () {
        // What my daemon does...
    }),
    new Control()
);
$child->start(); // Runs the callback in the background

The above example runs the Daemon action in the background, but one can use any class which implements
the Arara\Process\Action\Action interface like Callback action.

Check if the process is running

Checking to see if a process is running is a very common routine; to perform this using this library you may call:

$child->isRunning(); // Returns TRUE if it is running or FALSE if it is not

This method not only checks the state of the object, but also checks to see if the process is already running on the system.

Terminating the process

If the process has already started, this tells the process to terminate, but does not force it.

$child->terminate(); // Sends a SIGTERM to the process

Killing the process

If it has already started, this forces the process to terminate immediately.

$child->kill(); // Sends a SIGKILL to the process

Waiting on the process

If you want to wait on the process to finish, instead of just starting the process in the background, you can call:

$child->wait();

The next line of code will be executed after the process finishes.

Getting a process' status

It is possible to get the status of a process after waiting for it finish.
The Arara\Process\Child class has a method getStatus() which allows you to check the status of a process.

$child->getStatus(); // Returns an Arara\Process\Control\Status instance

Internally, this calls the wait() method, in order to wait for the process to finish - and then get its status.

Get the exit code of the process

$child->getStatus()->getExitStatus();

Get the signal which caused the process to stop

$child->getStatus()->getStopSignal();

Get the signal which caused the process to terminate

$child->getStatus()->getTerminateSignal();

Checks if the status code represents a normal exit

$child->getStatus()->isExited();

Checks whether the status code represents a termination due to a signal

$child->getStatus()->isSignaled();

Checks whether the process is stopped

$child->getStatus()->isStopped();

Checks if the process was finished successfully

$child->getStatus()->isSuccessful();

Spawning

Since you are working with forks you are able work with spawn as well. The Arara\Process\Pool class provides a simple
way to work with it.

This class handles the queue of process dynamically, the only thing you have to do is provide the limit of children you
want in the constructor and then attach the children.

$maxConcurrentChildren = 2;
$pool = new Pool($maxConcurrentChildren);
$pool->start();

$pool->attach(new Child(/* ... */));
$pool->attach(new Child(/* ... */));
$pool->attach(new Child(/* ... */));
$pool->attach(new Child(/* ... */));
// ...

The number of children it has does not matter; it will only run 2 process simultaneously; when one of those process is
finished, it is removed from the queue and a new slot is opened.

The Arara\Process\Pool class contains most of the methods of Arara\Process\Child class:

This behaves similarly for all methods.

Control class

You can also handle processes without using Pool, Child or the Action classes.

We provide a simple API to work with the pcntl_* and posix_* functions. You can learn more by reading the
code of Arara\Process\Control and its dependencies, but here is an example:

$control = new Control();
$pid = $control->fork();// Throws RuntimeException when pcntl_fork() returns -1
if ($pid > 0) {
    echo 'Waiting on child...' . PHP_EOL;
    $control->waitProcessId($pid);
    echo 'Child finished' . PHP_EOL;
    $control->quit();
}

echo 'Child process has PID ' . $control->info()->getId() . PHP_EOL;
echo 'Child process has parent PID ' . $control->info()->getParentId() . PHP_EOL;

$control->flush(2.5); // Will try to flush current process memory and sleep by 2 and a half seconds
$control->signal()->send('kill'); // Will send SIGKILL to the current process (the child)

Pidfile class

If you are working with background tasks you may want to create a lock to avoid people running your script twice. For this
purpose there is the class Arara\Process\Pidfile.

$control = new Control();
$applicationName = 'my_app';
$pidfile = new Pidfile($control, $applicationName);
$pidfile->initialize();

// Whatever you need here...

$pidfile->finalize();

The second time someone runs it an exception is thrown. We recommend you put this code into a try..catch statement.