Skip to content
CONTEXT(3)rasuvaeff PHP Library ManualCONTEXT(3)

NAME ​

context — deadlines, cancellation and request-scoped values for PHP

SYNOPSIS ​

$ composer require rasuvaeff/context

$root = Context::background();never terminates by itself [$request, $requestController] = $root->withTimeout(3.0);seconds[$step, $stepController] = $request->withCancel();cancellable branch $traced = $request->withValue(RequestId::class, new RequestId('r-42'));$traced->value(RequestId::class)?->value;'r-42' (nearest ancestor wins) [$work] = $request->withReserve(0.2);the parent deadline minus 200 ms

DESCRIPTION ​

Go's context.Context for PHP, with no dependencies. One budget follows a request through every layer.

Without a shared budget each layer has its own notion of time, so code can start a step after the request's budget is gone. Callers check one immutable deadline instead.

  • withTimeout, withDeadline, withCancel, withReserve derive child contexts.
  • A child deadline is never later than its parent's.
  • assertActive() throws ContextCancelledException or ContextExpiredException.
  • remainingMs() maps the budget to a transport timeout.
  • onTerminate() listeners; requestCancel() is safe in signal handlers.
  • iterate() and sleep() respect the deadline.
  • WireCodec carries the budget and allow-listed values across processes, with no unserialize().
  • FakeTimeSource and SteppingTimeSource for deterministic tests.

EXAMPLES ​

A queue worker uses the job's TTR as a deadline and acknowledges only when every step finished in time.

[$jobContext, $jobController] = Context::background()->withTimeout($ttrSeconds);try {    foreach ($steps as $step) {        $jobContext->assertActive();        $step($jobContext);    }    $queue->ack($message);} catch (ContextExpiredException) {    $queue->nack($message);  // let the queue decide retry/dead-letter} finally {    $jobController->cancel();}

WireCodec carries the remaining budget and typed values across a process boundary, treating input as untrusted.

$codec = new WireCodec(['tenant' => TenantId::class]); $message->attributes = $codec->encode($context);  // ['budget_ms' => 790, 'values' => ['tenant' => 'acme']] [$context, $controller] = $codec->decode($message->attributes, Context::background(), maxBudgetMs: 30_000);

A fake clock makes deadline tests deterministic: advance time and the context expires.

$clock = new FakeTimeSource();also the Sleeper: sleep() advances it[$context] = Context::background($clock)->withTimeout(1.0);$clock->advanceMs(2_000);$context->isExpired();true

SEE ALSO ​

PackageLayer
context-http(3)PSR-15 / PSR-18 and Guzzle
context-db(3)Statement timeouts on MySQL, MariaDB, PostgreSQL
context-cli(3)Graceful shutdown on OS signals
context-process(3)Subprocesses stopped at the deadline
clickhouse-toolkit(3)max_execution_time

resilience takes an optional context budget and composes retry, circuit-breaker and bulkhead in the order that does not amplify overload: bulkhead innermost, breaker around it, retry outside.

BUGS ​

The context stops work, it does not interrupt it. Cancellation is cooperative and deadlines are lazy (no background timer), so check before every step. Without context-db an in-flight PDO query cannot be aborted, and a blocking Redis call never can.

DEPENDENCIES

required by: bulkhead(3), clickhouse-toolkit(3), context-cli(3), context-db(3), context-http(3), context-process(3), resilience(3), retry(3), yii3-clickhouse-toolkit(3)

HISTORY

First released as v0.1.0 on 2026-10-10; 3 releases in all.

v0.3.02026-10-15
v0.2.02026-10-11
v0.1.02026-10-10
rasuvaeff/context 0.3.0mutation gate 90%used by 9 packagesCONTEXT(3)

/ search · n N next, previous · g G top, bottom · q back to the index