Pokio Laravel Package

Product Decisions This Supports

• Build vs. buy on internal tooling throughput. Pokio is a two-function, MIT-licensed, zero-configuration dependency (composer require, PHP 8.3+, done). The commitment level is near-zero and reversible by deleting two function calls, so the decision it informs is "is a cheap parallel-fan-out primitive worth a pilot?" — not "do we adopt a concurrency platform?"
• Roadmap placement. This belongs on a developer experience / CI throughput line item owned by Platform or DevEx, not on a customer-facing roadmap. It should never appear in a release narrative to customers.
• The "do we need a queue?" question. Pokio is a useful forcing function here. If the workload is a short-lived CLI script fanning out independent, I/O-bound units with no retries, priorities, idempotency, or per-task telemetry, Pokio can defer a Laravel Queues/Horizon investment. If any of those properties are required, that is a decisive no and pushes you straight to Queues. Framing the decision this way prevents a tooling shortcut from quietly becoming a scheduling architecture.
• Feature-level use cases to scope into a pilot: parallel Artisan commands, multi-endpoint smoke tests, seeding and backfill batching, static analysis across many paths, multi-tenant or multi-region CLI sweeps, and support for parallel test execution.
• Platform baseline decisions this surfaces. The package forces explicit answers on two infrastructure policies: (1) is the fleet uniformly on PHP 8.3+, and (2) do our CI runners, developer machines, and container images have PCNTL and FFI available? Those are real, reusable decisions regardless of whether Pokio ships.
• Risk acceptance as a named decision. The maintainer's README states plainly that it uses "low-level and potentially unsafe techniques" and is "intended strictly for internal use… Don't use this in production." Adopting it is a deliberate, documented override with a named owner — not a passive default that drifts into the request path.
• Fallback economics. Because PCNTL or FFI absence degrades to sequential execution rather than throwing, an environment-compatibility problem becomes a performance-variance problem. That is a much cheaper risk class to carry, and it is the single strongest argument for a low-stakes pilot.

When to Consider This Package

Criteria for adoption — all of these should hold:

• The call site is a short-lived CLI process on Unix that fans out independent, I/O-bound work and then exits. That is the only execution shape it fits.
• Wall-clock time is dominated by waiting. Measure the target script first. If it is CPU-bound, stop — forking buys nothing.
• PCNTL and FFI are both available, and you have verified the script is correct and acceptably fast under sequential fallback, because that is what Windows hosts, hardened containers, and restricted shared hosts will get.
• PHP 8.3+ is guaranteed everywhere the script runs. This is the only hard blocker; confirm it before anything else.
• Fan-out is bounded and you control the loop. There is no pool, no concurrency limit, no backpressure — one async() call is one OS process, so a naive loop over 500 records spawns 500 children.
• No forked child touches a database write, a socket, or shared mutable state. Forking clones the parent's heap — open PDO connections, Redis sockets, held locks, Guzzle clients, log handlers — into a child that no longer exclusively owns them.
• The script is correct without concurrency. Never let ordering, side-effect isolation, or timing depend on true parallelism.
• Global function name collisions (async, await) have been audited against existing helpers and vendor code.
• Single-maintainer risk is acceptable given MIT licensing, a small surface area, and the fallback being "vendor it" rather than "it disappears."

When to look elsewhere:

• Production request paths, Octane workers, queue workers, or daemons. Forking inside a long-lived worker is a data-corruption bug class, not a performance technique.
• You need retries, priorities, idempotency guarantees, or per-task telemetry → Laravel Queues, Horizon, Symfony Messenger.
• The work is parallel HTTP calls → Laravel's Http::pool(). Check this first, every time.
• You want a general concurrency primitive in the framework → Laravel's Concurrency helper.
• You need built-in pooling, process limits, or backpressure → spatie/async, symfony/process, amphp, or ReactPHP.
• Windows is a supported developer environment for the script, or you require a vendor SLA / long-term support commitment.
• The measured speedup is small. Don't adopt a "use at your own risk" dependency for a marginal gain.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are evaluating a small, MIT-licensed, zero-infrastructure library that lets internal command-line scripts run several independent tasks at once instead of one after another. The realistic upside is reduced CI wall-clock and less developer waiting on tooling — not a new customer capability. Cost is a Composer dependency and roughly a two-week, single-owner pilot in one repository. Its creator explicitly warns against production use, so we are scoping it strictly to developer tooling and CI, keeping it off the customer roadmap, and treating the decision as reversible by removing two function calls. The reason the risk is contained is that it silently falls back to ordinary sequential execution wherever the required PHP extensions aren't available, so the code stays correct and merely loses speed.

For engineering (the framing that matters): This is not a Laravel package — no service provider, no config file, no facade, no container bindings. It is two global functions, async() and await(), layered over PCNTL process forking with FFI-backed shared memory for inter-process communication. That reframes the integration question from "does it fit our framework?" to "does it fit the execution context we'd call it from?" — and the answer is yes only for short-lived CLI fan-out.

The four things to say out loud in review:

1. The maintainer says don't ship it to production. Overriding that needs a documented decision and an owner.
2. Fork safety is the real hazard. Any dependency holding inherited state across the fork boundary — DB clients, connection pools, RNG state, file handles — becomes a source of intermittent corruption that won't reproduce locally and won't show up in code review.
3. There is no concurrency control. One async() is one process; copy-on-write means a fully bootstrapped Laravel container amplifies the cost of every child. Bound the loop yourself.
4. Platforms will diverge. Linux CI, macOS laptops, and Windows machines produce three different timing profiles and, on Windows, different failure semantics — CI can silently become the only place real concurrency is ever exercised.

Two supporting notes worth including: the v1.0.1 release disables forking when Xdebug's debug mode is active, which turns "parallelism breaks my debugger" into a documented, silent degradation; and the package currently shows zero dependents, so we are early — which is an argument for a time-boxed pilot with a named owner and an upstream version watch, not an argument against trying it.

Finally, commit to measurement, not a promise: benchmark two representative scripts on our own hardware, record the actual numbers, and do not put a percentage improvement into any planning document until those numbers exist.