PHPackages                             lucinda/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. lucinda/process

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

lucinda/process
===============

Light weight API performing single/multiple shell command execution using IO multiplexing

v3.0.1(3w ago)019MITPHPPHP ^8.1

Since Mar 28Pushed 3w ago1 watchersCompare

[ Source](https://github.com/aherne/shell-processes)[ Packagist](https://packagist.org/packages/lucinda/process)[ RSS](/packages/lucinda-process/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (2)Versions (11)Used By (0)

Lucinda Shell Process & Pooling API
=======================================

[](#lucinda-shell-process--pooling-api)

This API is a light weight wrapper over PHP proc\_\* functions, able to execute shell processes individually, pool them or handle streams that traverse them. Its design goals were:

- **platform agnosticity**: API doesn't take any assumptions on the operating system process runs into
- **least assumption principle**: API doesn't take any assumption how you will handle process streams, so provides a skeleton instead
- **elegance and simplicity**: API is written on *less is more* principle so it's easy to understand and flexible to extend

API is 100% unit tested, fully PSR-4 compliant and only requiring PHP 8.1+ interpreter. For installation, you just need to write this in console:

```
composer require lucinda/process
```

Then use one of main classes provided (using use **Lucinda\\Shell** namespace):

- [Stream](https://github.com/aherne/shell-processes/blob/master/src/Stream.php): encapsulates an abstract data stream to be used by process (eg: STDIN/STDOUT/STDER). Extended by:
    - [Stream\\Pipe](https://github.com/aherne/shell-processes/blob/master/src/Stream/Pipe.php): encapsulates a stream of un-named pipes to be processed immediately
    - [Stream\\File](https://github.com/aherne/shell-processes/blob/master/src/Stream/File.php): encapsulates a stream of that delegates to a file on disk
    - [Stream\\Resource](https://github.com/aherne/shell-processes/blob/master/src/Stream/Resource.php): encapsulates a stream of that delegates to a *resource* (eg: socket)
- [Process](https://github.com/aherne/shell-processes/blob/master/src/Process.php): encapsulates a single process using [Stream](https://github.com/aherne/shell-processes/blob/master/src/Stream.php) instances above
- [Pool](https://github.com/aherne/shell-processes/blob/master/src/Pool.php): encapsulates a pool of processes to be executed in paralel queue-ing [Process](https://github.com/aherne/shell-processes/blob/master/src/Process.php) instances above and using [Process\\Multiplexer](https://github.com/aherne/shell-processes/blob/master/src/Process/Multiplexer.php) implementation for processing

Each of above classes branches through its methods to deeper classes that become relevant depending on the complexity of process execution logic. To make things simple following drivers were provided (using **Lucinda\\Shell\\Driver** namespace):

- [SingleCommandRunner](https://github.com/aherne/shell-processes/blob/master/drivers/SingleCommandRunner.php): executes a single [Process](https://github.com/aherne/shell-processes/blob/master/src/Process.php) and returns [Process\\Result](https://github.com/aherne/shell-processes/blob/master/src/Process/Result.php)
- [MultiCommandRunner](https://github.com/aherne/shell-processes/blob/master/drivers/MultiCommandRunner.php): executes list of [Process](https://github.com/aherne/shell-processes/blob/master/src/Process.php)-es and returns list of [Process\\Result](https://github.com/aherne/shell-processes/blob/master/src/Process/Result.php)-s

Both classes make use of I/O multiplexing that uses SELECT command underneath.

Executing Single Processes
--------------------------

[](#executing-single-processes)

To execute a single shell command you can use [Lucinda\\Shell\\Process](https://github.com/aherne/shell-processes/blob/master/src/Process.php) for minute control or [Lucinda\\Shell\\Driver\\SingleCommandRunner](https://github.com/aherne/shell-processes/blob/master/drivers/SingleCommandRunner.php) driver provided:

```
use Lucinda\Shell\Driver\SingleCommandRunner;
use Lucinda\Shell\Process;

$object = new SingleCommandRunner(5);
$result = $object->run(new Process("YOUR_SHELL_COMMAND"));
```

This is superior to **shell\_exec** because it will:

- terminate if shell command execution exceeds 5 seconds
- process STDOUT/STDERR streams separately using IO multiplexing
- read streams in parallel using chunks
- automatically escape shell command

Executing Multiple Processes
----------------------------

[](#executing-multiple-processes)

To execute multiple shell commands at once you can implement your own [Lucinda\\Shell\\Process\\Multiplexer](https://github.com/aherne/shell-processes/blob/master/src/Process%5CMultiplexer.php) for minute control or [Lucinda\\Shell\\Driver\\MultiCommandRunner](https://github.com/aherne/shell-processes/blob/master/drivers/MultiCommandRunner.php) driver provided:

```
use Lucinda\Shell\Driver\MultiCommandRunner;
use Lucinda\Shell\Process;

$object = new MultiCommandRunner(5);
$results = $object->run([
  new Process("YOUR_SHELL_COMMAND1"),
  new Process("YOUR_SHELL_COMMAND2"),
  ...
]);
```

This will:

- open processes simultaneously
- terminate if ANY of processes exceeds 5 seconds
- use non-blocking approach, allowing streams processing to be done in parallel
- automatically escape shell commands

### Pooling Multiplexed Processes

[](#pooling-multiplexed-processes)

To run multiplexed processes in pools of fixed size (5 in this example):

```
use Lucinda\Shell\Driver\MultiCommandRunner;
use Lucinda\Shell\Process;
use Lucinda\Shell\Pool;

# defines a pool of max 5 capacity
$pool = new Pool(5);
# adds processes to pool
$pool->submit(new Process("YOUR_SHELL_COMMAND1"));
$pool->submit(new Process("YOUR_SHELL_COMMAND2"));
...
# executes processes in batches, delegating to Multiplexer instances
$results = $pool->shutdown(new MultiCommandRunner(5));
```

This will:

- execute N processes at same time (5 in above example)
- when they all end, proceed to next batch

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance94

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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 ~210 days

Recently: every ~402 days

Total

10

Last Release

26d ago

Major Versions

v1.0.1 → v2.0.02021-12-30

v1.0.x-dev → v2.0.12022-01-09

v2.0.x-dev → v3.0.12026-06-07

PHP version history (3 changes)v1.0.0PHP ^7.1

v2.0.0PHP ^8.1

v1.0.2PHP ^7.1|^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3382770?v=4)[Lucian Gabriel Popescu](/maintainers/aherne)[@aherne](https://github.com/aherne)

---

Top Contributors

[![aherne](https://avatars.githubusercontent.com/u/3382770?v=4)](https://github.com/aherne "aherne (13 commits)")

---

Tags

processStreamspoolstdoutstdinstderrio multiplexing

### Embed Badge

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

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

###  Alternatives

[react/child-process

Event-driven library for executing child processes with ReactPHP.

34691.0M159](/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)[phpmentors/workflower

A BPMN 2.0 workflow engine for PHP

71256.1k4](/packages/phpmentors-workflower)[duncan3dc/fork-helper

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

81574.0k4](/packages/duncan3dc-fork-helper)[arara/process

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

16862.8k2](/packages/arara-process)[cekurte/environment

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

5887.0k9](/packages/cekurte-environment)

PHPackages © 2026

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