PHPackages                             nick4fake/react-child-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. nick4fake/react-child-process

Abandoned → [nick4fake/react-child-process](/?search=nick4fake%2Freact-child-process)Library[Utility & Helpers](/categories/utility)

nick4fake/react-child-process
=============================

Library for executing child processes.

v0.4.3(9y ago)012MITPHPPHP >=5.3.0

Since Feb 2Pushed 9y ago1 watchersCompare

[ Source](https://github.com/nick4fake/child-process)[ Packagist](https://packagist.org/packages/nick4fake/react-child-process)[ RSS](/packages/nick4fake-react-child-process/feed)WikiDiscussions master Synced 4d ago

READMEChangelogDependencies (5)Versions (8)Used By (0)

Child Process Component
=======================

[](#child-process-component)

[![Build Status](https://camo.githubusercontent.com/61427d936f084646c734ae58969c9f858a2023994a76190f76d4994d792cd7c4/68747470733a2f2f7365637572652e7472617669732d63692e6f72672f72656163747068702f6368696c642d70726f636573732e706e673f6272616e63683d6d6173746572)](http://travis-ci.org/reactphp/child-process) [![Code Climate](https://camo.githubusercontent.com/9cddecd293dbecd55d558d1a13a09c2909ba717a56b4f5452544101b7852991e/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f72656163747068702f6368696c642d70726f636573732f6261646765732f6770612e737667)](https://codeclimate.com/github/reactphp/child-process)

Library for executing child processes.

This library integrates [Program Execution](http://php.net/manual/en/book.exec.php)with the [EventLoop](https://github.com/reactphp/event-loop). Child processes launched may be signaled and will emit an `exit` event upon termination. Additionally, process I/O streams (i.e. STDIN, STDOUT, STDERR) are exposed as [Streams](https://github.com/reactphp/stream).

**Table of contents**

- [Quickstart example](#quickstart-example)
- [Processes](#processes)
    - [EventEmitter Events](#eventemitter-events)
    - [Methods](#methods)
    - [Stream Properties](#stream-properties)
    - [Command](#command)
    - [Sigchild Compatibility](#sigchild-compatibility)
- [Install](#install)
- [Tests](#tests)
- [License](#license)

Quickstart example
------------------

[](#quickstart-example)

```
$loop = React\EventLoop\Factory::create();

$process = new React\ChildProcess\Process('echo foo');
$process->start($loop);

$process->stdout->on('data', function ($chunk) {
    echo $chunk;
});

$process->on('exit', function($exitCode, $termSignal) {
    echo 'Process exited with code ' . $exitCode . PHP_EOL;
});

$loop->run();
```

See also the [examples](examples).

Processes
---------

[](#processes)

### EventEmitter Events

[](#eventemitter-events)

- `exit`: Emitted whenever the process is no longer running. Event listeners will receive the exit code and termination signal as two arguments.

### Methods

[](#methods)

- `start()`: Launches the process and registers its IO streams with the event loop. The stdin stream will be left in a paused state.
- `terminate()`: Send the process a signal (SIGTERM by default).

There are additional public methods on the Process class, which may be used to access fields otherwise available through `proc_get_status()`.

### Stream Properties

[](#stream-properties)

Once a process is started, its I/O streams will be constructed as instances of `React\Stream\Stream`. Before `start()` is called, these properties are `null`. Once a process terminates, the streams will become closed but not unset.

- `$stdin`
- `$stdout`
- `$stderr`

Each of these implement the underlying [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface)and you can use any of its events and methods as usual:

```
$process->stdout->on('data', function ($chunk) {
    echo $chunk;
});

$process->stdout->on('end', function () {
    echo 'ended';
});

$process->stdout->on('error', function (Exception $e) {
    echo 'error: ' . $e->getMessage();
});

$process->stdout->on('close', function () {
    echo 'closed';
});

$process->stdin->write($data);
$process->stdin->end($data = null);
$process->stdin->close();
// …
```

For more details, see the [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface).

### Command

[](#command)

The `Process` class allows you to pass any kind of command line string:

```
$process = new Process('echo test');
```

By default, PHP will launch processes by wrapping the given command line string in a `sh` command, so that the above example will actually execute `sh -c echo test` under the hood.

This is a very useful feature because it does not only allow you to pass single commands, but actually allows you to pass any kind of shell command line and launch multiple sub-commands using command chains (with `&&`, `||`, `;` and others) and allows you to redirect STDIO streams (with `2>&1` and family). This can be used to pass complete command lines and receive the resulting STDIO streams from the wrapping shell command like this:

```
$process = new Process('echo run && demo || echo failed');
```

In other words, the underlying shell is responsible for managing this command line and launching the individual sub-commands and connecting their STDIO streams as appropriate. This implies that the `Process` class will only receive the resulting STDIO streams from the wrapping shell, which will thus contain the complete input/output with no way to discern the input/output of single sub-commands.

If you want to discern the output of single sub-commands, you may want to implement some higher-level protocol logic, such as printing an explicit boundary between each sub-command like this:

```
$process = new Process('cat first && echo --- && cat second');
```

As an alternative, considering launching one process at a time and listening on its `exit` event to conditionally start the next process in the chain. This will give you an opportunity to configure the subsequent process I/O streams:

```
$first = new Process('cat first');
$first->start($loop);

$first->on('exit', function () use ($loop) {
    $second = new Process('cat second');
    $second->start($loop);
});
```

Keep in mind that PHP uses the shell wrapper for ALL command lines. While this may seem reasonable for more complex command lines, this actually also applies to running the most simple single command:

```
$process = new Process('yes');
```

This will actually spawn a command hierarchy similar to this:

```
5480 … \_ php example.php
5481 …    \_ sh -c yes
5482 …        \_ yes

```

This means that trying to get the underlying process PID or sending signals will actually target the wrapping shell, which may not be the desired result in many cases.

If you do not want this wrapping shell process to show up, you can simply prepend the command string with `exec`, which will cause the wrapping shell process to be replaced by our process:

```
$process = new Process('exec yes');
```

This will show a resulting command hierarchy similar to this:

```
5480 … \_ php example.php
5481 …    \_ yes

```

This means that trying to get the underlying process PID and sending signals will now target the actual command as expected.

Note that in this case, the command line will not be run in a wrapping shell. This implies that when using `exec`, there's no way to pass command lines such as those containing command chains or redirected STDIO streams.

As a rule of thumb, most commands will likely run just fine with the wrapping shell. If you pass a complete command line (or are unsure), you SHOULD most likely keep the wrapping shell. If you want to pass an invidual command only, you MAY want to consider prepending the command string with `exec` to avoid the wrapping shell.

### Sigchild Compatibility

[](#sigchild-compatibility)

When PHP has been compiled with the `--enabled-sigchild` option, a child process' exit code cannot be reliably determined via `proc_close()` or `proc_get_status()`. Instead, we execute the child process with a fourth pipe and use that to retrieve its exit code.

This behavior is used by default and only when necessary. It may be manually disabled by calling `setEnhanceSigchildCompatibility(false)` on the Process before it is started, in which case the `exit` event may receive `null` instead of the actual exit code.

**Note:** This functionality was taken from Symfony's [Process](https://github.com/symfony/process) compoment.

Install
-------

[](#install)

The recommended way to install this library is [through Composer](http://getcomposer.org). [New to Composer?](http://getcomposer.org/doc/00-intro.md)

This will install the latest supported version:

```
$ composer require react/child-process:^0.4.3
```

More details about version upgrades can be found in the [CHANGELOG](CHANGELOG.md).

Tests
-----

[](#tests)

To run the test suite, you first need to clone this repo and then install all dependencies [through Composer](http://getcomposer.org):

```
$ composer install
```

To run the test suite, go to the project root and run:

```
$ php vendor/bin/phpunit
```

License
-------

[](#license)

MIT, see [LICENSE file](LICENSE).

###  Health Score

25

—

LowBetter than 35% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor2

2 contributors hold 50%+ of commits

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 ~227 days

Recently: every ~239 days

Total

6

Last Release

3396d ago

PHP version history (2 changes)v0.4.0PHP >=5.4.0

0.3.x-devPHP >=5.3.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/533d0c99c4e0c7413a1dcce2d81c37ecf94883e6377d274d6f43247a399bb268?d=identicon)[nick4fake](/maintainers/nick4fake)

---

Top Contributors

[![clue](https://avatars.githubusercontent.com/u/776829?v=4)](https://github.com/clue "clue (21 commits)")[![jmikola](https://avatars.githubusercontent.com/u/244663?v=4)](https://github.com/jmikola "jmikola (20 commits)")[![cboden](https://avatars.githubusercontent.com/u/617694?v=4)](https://github.com/cboden "cboden (17 commits)")[![WyriHaximus](https://avatars.githubusercontent.com/u/147145?v=4)](https://github.com/WyriHaximus "WyriHaximus (12 commits)")[![igorw](https://avatars.githubusercontent.com/u/88061?v=4)](https://github.com/igorw "igorw (2 commits)")[![staabm](https://avatars.githubusercontent.com/u/120441?v=4)](https://github.com/staabm "staabm (2 commits)")[![e3betht](https://avatars.githubusercontent.com/u/1811561?v=4)](https://github.com/e3betht "e3betht (1 commits)")[![jsor](https://avatars.githubusercontent.com/u/55574?v=4)](https://github.com/jsor "jsor (1 commits)")[![mbonneau](https://avatars.githubusercontent.com/u/748287?v=4)](https://github.com/mbonneau "mbonneau (1 commits)")

---

Tags

process

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/nick4fake-react-child-process/health.svg)

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

###  Alternatives

[friendsofphp/php-cs-fixer

A tool to automatically fix PHP code style

13.5k251.2M24.7k](/packages/friendsofphp-php-cs-fixer)[ccxt/ccxt

A cryptocurrency trading API with more than 100 exchanges in JavaScript / TypeScript / Python / C# / PHP / Go

43.2k341.0k1](/packages/ccxt-ccxt)[react/child-process

Event-driven library for executing child processes with ReactPHP.

34691.0M157](/packages/react-child-process)[cocur/background-process

Start processes in the background that continue running when the PHP process exists.

2982.0M12](/packages/cocur-background-process)[duncan3dc/fork-helper

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

81574.0k4](/packages/duncan3dc-fork-helper)[cekurte/environment

A library to get the values from environment variables and process to php data types

5887.0k8](/packages/cekurte-environment)

PHPackages © 2026

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