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

v2.0.3(3y ago)019MITPHPPHP ^8.1

Since Mar 28Pushed 3y ago1 watchersCompare

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

READMEChangelogDependencies (1)Versions (10)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

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity67

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

Recently: every ~36 days

Total

9

Last Release

1443d ago

Major Versions

v1.0.1 → v2.0.02021-12-30

v1.0.2 → v2.0.12022-01-09

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

v2.0.0PHP ^8.1

v1.0.x-devPHP ^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.

34076.1M136](/packages/react-child-process)[cocur/background-process

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

2971.9M12](/packages/cocur-background-process)[phpmentors/workflower

A BPMN 2.0 workflow engine for PHP

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

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

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

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

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

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

5884.0k7](/packages/cekurte-environment)

PHPackages © 2026

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