Download the PHP package bear/defer without Composer

BEAR.Defer

Deferred resource requests for BEAR.Resource — run resource requests after the response is transferred.

A resource accepts a request, returns 202 Accepted immediately, and the heavy follow-up work (indexing, notification, …) runs after the response has been sent to the client. The resource only declares what to defer; when and where it runs is decided by bindings, outside the resource — so the same application code works on CLI, PHP-FPM, Swoole, or a queue without change.

Design background: bearsunday/BEAR.Resource#373.

Installation

Then install DeferModule in your AppModule, passing the module that provides your responder — rename() moves that binding to the 'inner' qualifier automatically:

Usage

Declare what to defer

Annotate the accepting resource with #[Defer], listing #[Link] rels (no hardcoded URIs). Each rel's href is resolved against the resource body after the method runs. Because #[Defer] references #[Link] rels, the deferred transition stays hypermedia-driven and surfaces in ALPS as a deferred transition.

The follow-up resources are ordinary resources

They don't know they are deferred — any resource can be the target.

Conditional defer

When the follow-up work is conditional, inject DeferInterface and ResourceInterface directly and call $defer->add() manually. This bypasses #[Defer] and gives full control over what gets enqueued.

How it works

• DeferInterceptor — an After interceptor bound to #[Defer]. Once the method has run (so the body is set), it resolves each #[Link] href against the body and enqueues a Request on DeferInterface. Collecting at execution time means #[Defer] on #[Embed]-ed child resources is captured too.
• DeferTransfer — decorates TransferInterface: runs the base transfer ("how to send"), releases the client connection via ConnectionCloserInterface when the SAPI supports it, then calls DeferInterface::flush() ("flush after send").
• Binding — DeferModule receives the responder module via its constructor. rename(TransferInterface::class, 'inner') moves that module's TransferInterface binding to the 'inner' qualifier, then DeferTransfer is bound as the new TransferInterface. The resource never sees any of this.

Execution strategy

The bundled SyncDefer runs deferred requests sequentially, in-process, after the transfer. It keeps request-local state in a singleton cleared on every flush(), so it is correct on PHP-FPM / CLI as long as flush() runs for every request.

The strategy is chosen by binding DeferInterface; the application code (#[Defer]) never changes.

Releasing the client connection

So the client gets its response before the deferred work runs, DeferTransfer releases the connection between the transfer and the flush, through ConnectionCloserInterface (default: SapiConnectionCloser):

• PHP-FPM — fastcgi_finish_request()
• LiteSpeed — litespeed_finish_request()
• Other web SAPIs (e.g. Apache mod_php) — flush(), best-effort; no guaranteed early return
• CLI — nothing to release

A runtime with a different mechanism (e.g. Swoole's $response->end()) binds its own ConnectionCloserInterface to replace it.

Swoole / long-running workers

DeferInterface is a singleton whose queue is cleared at the request boundary by flush(). This gives per-request flushing on PHP-FPM / CLI without relying on process isolation. On a strictly coroutine-concurrent runtime where a single worker interleaves requests, per-request isolation must be provided by the runtime adapter; the core package does not address coroutine isolation.