Download the PHP package uncrackable404/concurrent-console-progress without Composer

Concurrent Console Progress

Introduction

Concurrent Console Progress is a live dashboard for PHP console applications that run many concurrent tasks across one or more queues. Typical use cases: bulk imports, fan-out API calls, background migrations, and any batch job where you want per-queue progress bars, aggregated counters, and atomic shared state updated in real time.

The package is powered by spatie/fork for process isolation and inspired by laravel/prompts for terminal rendering.

Requirements

• PHP ^8.3
• ext-pcntl, ext-posix (Unix-only — macOS, Linux)
• Works in CLI context only (forking is not available in FPM/Apache)

Installation

Usage

The package exposes:

• Uncrackable404\ConcurrentConsoleProgress\ConcurrentProgress — the main class.
• Uncrackable404\ConcurrentConsoleProgress\concurrent() — a convenience helper around ConcurrentProgress::run().
• Uncrackable404\ConcurrentConsoleProgress\ProgressState — the interface for the shared state your tasks can read and mutate.

Minimal Example

One queue, one counter, no shared state:

Complete Example

Multiple queues, custom columns, footer values, and free-form return values. Task state (progress, per-row counters, global footer values) flows through the ProgressState passed as the second argument — the callback's return value is free-form and is forwarded to the caller as-is.

Progress State API

The ProgressState interface exposes atomic read/write operations against state owned by the parent process. A ProgressState instance is injected into your task callback when the closure signature declares a second parameter:

• advance() increments the queue's processed counter (clamped to total) — this is what drives the progress bar.
• increment() is an atomic numeric counter over $global[$key] (when $queue === null) or $rows[$queue]['meta'][$key].
• transform() applies a closure atomically via a compare-and-set retry loop. The closure receives the current value (or null if unset) and returns the new value. Ideal for min / max aggregations where the result depends on the current value.
• get() returns the stored value or null. Use the null-coalescing operator for defaults: $state->get('credits') ?? 0.
• set() / compareAndSet() are the primitives backing the higher-level helpers.

When concurrent >= 1 the state lives in the parent process and child tasks communicate with it via a Unix-socket RPC (no state files, no extra extensions). When concurrent: 0 the state lives in memory of the single process.

Back-compat: the second parameter is optional. Single-argument closures fn (array $task) => … still work — you just don't get access to ProgressState.

Laravel Integration

The package ships with ConsoleProgressServiceProvider, auto-discovered by Laravel. It wires the command output into the dashboard, so you can use concurrent() inside any Artisan command with no extra configuration:

Synchronous Mode

Set concurrent: 0 to run all tasks sequentially in the same process, bypassing spatie/fork entirely. The rendering, state, and fail-fast logic are unchanged — only the execution is serial. Useful when debugging with dd(), dump(), or xdebug:

How It Works

• Process isolation. Each task runs in its own child process via pcntl_fork (through spatie/fork). A crash in one task does not affect the others, and memory leaks are bounded because every child exits after completion.
• Parent-owned shared state. ProgressState lives only in the parent. Children talk to it over a Unix-domain socket created in the system temp directory; no state file is ever written to disk. Operations (get, set, compareAndSet, advance, …) are synchronous RPC calls.
• Real-time rendering. After each state mutation the child wakes the parent with SIGUSR1; the parent drains the pending RPC, re-renders the dashboard, and returns. Frame throttling prevents flicker under rapid updates.
• Atomic aggregations. transform() runs a compare-and-set retry loop against the parent, so min / max / custom reducers work correctly even with many forked tasks updating the same key concurrently.
• Fail-fast. If any task throws, the parent tears down all running children and re-throws a snapshot exception with the original file, line, and trace preserved.

License

The MIT License (MIT).