Download the PHP package pogo/async without Composer

Pogo

Request-scoped parallel PHP tasks for FrankenPHP.

Pogo lets one PHP request spawn independent tasks in FrankenPHP worker pools, await their results, and return a response after the fan-out/fan-in work is done. It is built for bounded work such as independent API calls, CPU work, or response fragments.

Pogo is not a queue. Tasks are tied to the current request. There is no persistence, retry system, delay API, scheduler, event loop, fiber abstraction, or framework adapter in the core module.

API

Pogo exposes three native PHP functions:

Example:

pogo_await() throws RuntimeException for unknown tasks, timeouts, worker failures, invalid worker responses, and task exceptions returned by the worker. pogo_pool_size() throws RuntimeException when Pogo is not configured or the pool name is unknown.

Task Contract

There is no required Composer package and no required interface. A task class only needs to be autoloadable by your worker and expose a public handle(array $args): mixed method:

Arguments and return values must be JSON-compatible. Resources, closures, cyclic data, and unserializable objects are unsupported.

Worker Contract

Your application owns the worker bootstrap. The worker receives:

and must return one of these JSON-compatible envelopes:

The example worker in example/worker.php is a small production template: it boots the app, validates the payload, instantiates the class, calls handle(array $args), and converts exceptions to the error envelope.

Caddy

Configure Pogo as a FrankenPHP/Caddy global option. The top-level worker is the default pool. Add named pools when you need isolation for slow APIs, CPU-heavy tasks, or critical work.

Pool directives:

• worker: PHP worker script. Required.
• num_threads: FrankenPHP worker thread count. Optional.
• max_wait: maximum wait for SendMessage before the task fails. Optional, default 30s.

Task IDs are globally unique, so pogo_await() does not need the pool name.

Production Notes

Use Pogo for tasks that can safely fail with the request or be retried by the caller. Keep tasks bounded by request timeouts and pool max_wait values.

Use separate pools for workloads with different latency or capacity profiles. For example, do not run slow third-party API calls and CPU-heavy transforms in the same worker pool unless they can block each other safely.

Call pogo_await() for every task you need. Unawaited tasks are canceled at request shutdown.

Example

Build and run the included smoke app:

The response should show two sleeping tasks finishing in roughly one sleep duration, not the sum of both sleeps.

Build

Build a FrankenPHP binary that includes Pogo with xcaddy:

Then copy your app, worker script, and Caddyfile into the runner image.

Test

Run the full example smoke check:

Package

Go module: github.com/y-l-g/pogo/module