Parallel Bridge Laravel Package

Getting Started

1. Install via Composer: composer require publicplan/parallel-bridge. The package follows PSR-4 autoloading only — no bundle registration is required unless the README for the tagged version says otherwise. Check composer.json first to confirm what runtime it bridges (typically amphp/parallel, spatie/fork, or ext-parallel) and whether that peer dependency is already installed.
2. Skim the repo in this order: README.md → src/ (the public service/interface names) → tests/ (the tests are the only reliable documentation for a 3-star package). Note that with so few dependents, examples are sparse — treat the test suite as canonical usage.
3. Wire the main service into config/services.yaml (autowiring should pick it up if the package registers its services). Verify with bin/console debug:container | grep -i parallel.
4. First use case: parallelize a fan-out of independent, I/O-bound tasks (HTTP calls, external API lookups, file scans). Do not start with CPU-bound work — forked/threaded workers add serialization overhead that rarely pays off for small or CPU-heavy closures.

A minimal smoke test in a console command:

foreach ($tasks as $task) {
    $executor->add($task);          // enqueue
}
$results = $executor->wait();       // or ->run()

If that returns the same array shape you put in, you're wired up correctly.

Implementation Patterns

• Batch fan-out in commands: pull the parallel runner into a Symfony\Component\Console\Command\Command and chunk input into groups sized to min(cpu_count, n). This is the most common day-to-day use — offline imports, syncs, report generation.
• Service wrapper pattern: wrap the bridge in your own ParallelRunner service rather than injecting the raw bridge everywhere. This isolates the low-level API and makes it swappable when (not if) you migrate off a 3-star dependency.
• Result aggregation: have workers return plain scalars or arrays; aggregate in the parent. Avoid returning entities or services across the boundary.
• Messenger integration: for long-running job batches, enqueue per-task messages onto a Messenger transport and use multiple messenger:consume workers instead of forking inside a single process. The bridge is best for short-lived, in-process parallelism; Messenger is better for durable pipelines.
• Testing: mock the executor interface in unit tests; run the real bridge only in integration tests, and keep worker counts at 1–2 in CI to avoid flaky serialization failures.
• Config-first tuning: expose pool size / timeout as parameters in config/packages/parallel_bridge.yaml (or your own bundle config) so ops can tune without code changes.

Gotchas and Tips

• Serialization boundaries: workers run in separate processes/threads. Closures capturing $this, Symfony services, or Doctrine entities will fail or silently lose state. Pass plain data (arrays, scalars, DTOs with #[Serializable]-style shapes).
• Peer dependency mismatch: the package is a bridge — the real work is done by amphp/parallel, spatie/fork, etc. Pin that peer version explicitly in your composer.json; bridge releases rarely constrain it tightly enough.
• Debugging interleaved output: worker echo/dump calls may interleave or vanish. Log to files (Monolog channels per worker) or return structured results and print in the parent. Xdebug inside forked workers is often broken — disable it in worker contexts.
• Autoloader in forked children: if you fork from a Composer dev context, ensure vendor/autoload.php is loaded in the child. Some bridges do this; some don't. Test under APP_ENV=prod before trusting it.
• Error propagation: exceptions thrown in a worker are often wrapped or dropped. Decide in your wrapper whether a single failing task aborts the batch or returns a partial result set — the bridge usually won't decide for you.
• Container bootstrapping: each worker may boot a fresh kernel, which means DB connections, env vars, and cache warmers run per worker. Account for connection-pool exhaustion with large pools.
• Project risk: 3 stars, 0 dependents, single-primary license. Vendor a copy or wrap behind an interface so a composer remove is a one-file change. Watch the repo for the last-pushed date — if it's stale, plan to migrate.
• Extension points: check for a ParallelExecutorInterface or similar in src/; that (not the concrete class) is what you should type-hint in your own services so you can plug in a fake or a replacement later.