PHPackages                             arara/process - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. arara/process

ActiveLibrary[Utility & Helpers](/categories/utility)

arara/process
=============

Provides a better API to work with processes on Unix-like systems

1.10.0(10y ago)16861.7k↓40.9%15[1 issues](https://github.com/Arara/Process/issues)2MITPHPPHP >=5.4.0

Since Feb 14Pushed 10y ago16 watchersCompare

[ Source](https://github.com/Arara/Process)[ Packagist](https://packagist.org/packages/arara/process)[ Docs](https://github.com/Arara/Process)[ RSS](/packages/arara-process/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (30)Used By (2)

Arara\\Process
==============

[](#araraprocess)

[![Build Status](https://camo.githubusercontent.com/0f4064de3c0a7f05093ad744b5b79c10aa6d6494647b618f16c246768412c928/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f41726172612f50726f636573732f6d61737465722e7376673f7374796c653d666c61742d737175617265)](http://travis-ci.org/Arara/Process)[![Code Quality](https://camo.githubusercontent.com/ad957c27f7f073af3d28acf8d0fcd3aed98d80197be7a63fa444f2b4061c30e9/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f41726172612f50726f636573732f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/Arara/Process/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/01e97f2c5e6ee876b8a9219e58b66c0ac0136491ecd4b15ad44d63418165a2c8/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f41726172612f50726f636573732f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/Arara/Process/?branch=master)[![Latest Version](https://camo.githubusercontent.com/2c3e1dd81a1f219f24b6670d932538647b6301d14f4f89890b06c64c9ece84d6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61726172612f70726f636573732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/arara/process)[![Total Downloads](https://camo.githubusercontent.com/55ce3f1642703b772b862134675bc265e11645403d1360909e58b507b4d52406/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f61726172612f70726f636573732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/arara/process)[![License](https://camo.githubusercontent.com/cd81a00bfd015c0a892e1405ea7ba43643867bdc1712d58219ff43a38bf4d9f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f61726172612f70726f636573732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/arara/process)

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

Installation
------------

[](#installation)

The package is available on [Packagist](https://packagist.org/packages/arara/process). You can install it using [Composer](http://getcomposer.org).

```
composer require arara/process
```

### Dependencies

[](#dependencies)

- PHP 5.4+
- [PCNTL](http://php.net/pcntl)
- [POSIX](http://php.net/posix)
- [PHPFluent\\Callback](https://github.com/PHPFluent/Callback) (installed by Composer)

Version [1.6.0](https://github.com/Arara/Process/tree/1.6.0) or less of Arara\\Process works on PHP 5.3.

Usage
-----

[](#usage)

Along with this document, there are many usage examples in the [examples/](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 .

### Action interface

[](#action-interface)

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

- `execute(..)`: may contain the action performed in the background
- `trigger(...)`: may contain specific actions to events

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

### Events

[](#events)

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

- `Action::EVENT_INIT`: triggered when action is initialized
    - When the action is attached to a Child object
- `Action::EVENT_FORK`: triggered when action is forked
    - After the action is forked it is triggered on the **parent** process
- `Action::EVENT_START`: triggered before the execute() method is executed
- `Action::EVENT_SUCCESS`: triggered when the action is finished with success, that is:
    - When the action does not encounter a PHP error
    - When the action does not throw an exception
    - When the action does not return any value
    - When the action returns an `Action::EVENT_SUCCESS` value
- `Action::EVENT_ERROR`: triggered when the action is encounters an error, that is:
    - When the action encounters a PHP error
    - When the action returns an `Action:EVENT_ERROR` value
- `Action::EVENT_FAILURE`: triggered after the action has finished and failed, that is:
    - When the action throws an exception
    - When the action returns an `Action::EVENT_FAILURE` value
- `Action::EVENT_TIMEOUT`: triggered when the action experiences a timeout
- `Action::EVENT_FINISH `: triggered after the execute() method has executed.

### Callback action

[](#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

[](#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

[](#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-options)

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

- `name`: Name used by pidfile (default *arara*)
- `lock_dir`: Lock directory for pidfile (default */var*/run)
- `work_dir`: Work directory (default */*)
- `umask`: Default umask value (default 0)
- `user_id`: When defined changed the daemon UID (default *NULL*)
- `group_id`: When defined changed the daemon GID (default *NULL*)
- `stdin`: File to use as `STDIN` (default */dev/null*)
- `stdout`: File to use as `STDOUT` (default */dev/null*)
- `stderr`: File to use as `STDERR` (default */dev/null*)

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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#get-the-exit-code-of-the-process)

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

#### Get the signal which caused the process to stop

[](#get-the-signal-which-caused-the-process-to-stop)

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

#### Get the signal which caused the process to terminate

[](#get-the-signal-which-caused-the-process-to-terminate)

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

#### Checks if the status code represents a normal exit

[](#checks-if-the-status-code-represents-a-normal-exit)

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

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

[](#checks-whether-the-status-code-represents-a-termination-due-to-a-signal)

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

#### Checks whether the process is stopped

[](#checks-whether-the-process-is-stopped)

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

#### Checks if the process was finished successfully

[](#checks-if-the-process-was-finished-successfully)

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

### Spawning

[](#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:

- `isRunning()`
- `kill()`
- `start()`
- `terminate()`
- `wait()`

This behaves similarly for all methods.

### Control class

[](#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

[](#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.

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity45

Moderate usage in the ecosystem

Community21

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 96.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~31 days

Recently: every ~36 days

Total

28

Last Release

4002d ago

Major Versions

0.8.0 → 1.0.02014-04-18

PHP version history (2 changes)0.1.0PHP >=5.3.0

1.7.0PHP >=5.4.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/154023?v=4)[Henrique Moody](/maintainers/henriquemoody)[@henriquemoody](https://github.com/henriquemoody)

---

Top Contributors

[![henriquemoody](https://avatars.githubusercontent.com/u/154023?v=4)](https://github.com/henriquemoody "henriquemoody (92 commits)")[![damoclark](https://avatars.githubusercontent.com/u/275110?v=4)](https://github.com/damoclark "damoclark (3 commits)")

---

Tags

posixprocesscommandtaskforkdaemonpcntlmultitaskingspawn

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/arara-process/health.svg)

```
[![Health](https://phpackages.com/badges/arara-process/health.svg)](https://phpackages.com/packages/arara-process)
```

###  Alternatives

[duncan3dc/fork-helper

Simple class to fork processes in PHP and allow multi-threading

73548.0k4](/packages/duncan3dc-fork-helper)[graze/supervisor

:vertical\_traffic\_light: Process supervisor for PHP.

999.3k](/packages/graze-supervisor)[symplely/coroutine

Cooperative multitasking using generators. The basics of coroutines, async and await!

621.6k2](/packages/symplely-coroutine)[lifo/php-ipc

Simple PHP Inter Process Communication (IPC) library

285.5k](/packages/lifo-php-ipc)[php-lrpm/php-lrpm

PHP Long Running Process Manager

187.8k1](/packages/php-lrpm-php-lrpm)[symfony-bundles/fork

SymfonyBundles Fork Library

178.0k](/packages/symfony-bundles-fork)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)