Context
Stack-based storage for named context values. A shared Context store holds a value per name and keeps a stack behind each name so contexts can be created and destroyed in any order. Typed wrappers give each context an input, output, mutable, value, parse or gather-lookup lifetime, and snapshots let a captured state be restored around a callback.
This page is a pure reference. For how the framework fits together, see the Guide.
Context- central stack-based store shared by every context type.ContextGatherLookup- gather key-value pairs into a lookup map.ContextInput- store, read and destroy a raw input value.ContextMutable- store a value that can be updated, then read back on destroy.ContextOutput- a value set exactly once before it is destroyed.ContextParse- parse an array one value at a time.ContextSnapshotData- a captured contexts and stacks state.ContextValue- store, read and destroy a raw value.
Context
The central store shared by every context type. It holds one current value per name in a contexts map and keeps a stack behind each name, so a name can be pushed and popped and still restore its previous value. It also captures and restores whole context states.
contexts
Context::contexts(): array
Internal access to the current contexts map, for use by the other context classes.
Returns array The contexts map.
Current
Context::Current(): array
A copy of the current context map with all contexts. Changes to the returned map do not affect the stored contexts.
Returns array A copy of the current context map.
Function
Context::Function(callable $callback): callable
Capture the current context and return a wrapper that restores it before invoking the callback, then restores the previous context afterwards. Useful when a callback runs later but still needs the context it was defined in.
| Name | Type | Description |
|---|---|---|
$callback | callable | The callback to wrap with the captured context. |
Returns callable A wrapper that restores the captured context around the callback.
Pop
Context::Pop(string $name): void
Remove the current value for a name. If a value is on that name's stack it is popped and made current; when the stack is empty the name is removed from the map. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns void
Push
Context::Push(string $name, mixed $value): void
Set a value for a name. Any existing value for that name is pushed onto its stack first, so contexts can be created and destroyed in any order.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$value | mixed | The value to set; the current value, if any, is pushed to the stack. |
Returns void
Restore
Context::Restore(array $context, callable $callback): void
Save the current context, restore the provided context map, run the callback, then restore the original context and stacks. The original state is restored even if the callback throws.
| Name | Type | Description |
|---|---|---|
$context | array | The context map to restore temporarily. |
$callback | callable | The callback to run with the restored context. |
Returns void
RestoreSnapshot
Context::RestoreSnapshot(ContextSnapshotData $snapshot, callable $callback): void
Restore a captured snapshot's contexts and stacks, run the callback, then restore the previous state afterwards, even if the callback throws.
| Name | Type | Description |
|---|---|---|
$snapshot | ContextSnapshotData | The snapshot to restore temporarily. |
$callback | callable | The callback to run with the restored snapshot. |
Returns void
Set
Context::Set(string $name, mixed $value): void
Set the current value of an existing context directly, without touching its stack. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$value | mixed | The value to set. |
Returns void
Snapshot
Context::Snapshot(): ContextSnapshotData
Capture the current contexts map and stack state as a snapshot.
Returns ContextSnapshotData The captured contexts and stacks.
ContextGatherLookup
Gather key-value pairs into a lookup map. Create starts an empty map, Entry adds a pair, and Destroy returns the gathered map. Nesting is supported by saving and restoring the previous map.
Create
ContextGatherLookup::Create(string $name): void
Start a gather lookup context with an empty map, saving any current value. The caller must call Destroy when finished.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns void
Destroy
ContextGatherLookup::Destroy(string $name): array
Return the lookup map of all pairs added, and pop the context, restoring any previous value. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns array The lookup map of gathered key-value pairs.
Entry
ContextGatherLookup::Entry(string $name, string $key, mixed $value): void
Add a key-value pair to the current gather lookup context. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$key | string | The lookup key. |
$value | mixed | The value to store. |
Returns void
ContextInput
Store, read and destroy a raw input value. Works with raw values directly, with nested contexts supported by saving and restoring previous values.
Create
ContextInput::Create(string $name, mixed $value): void
Store a raw value, saving any current value. The caller must call Destroy when finished.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$value | mixed | The raw value to store. |
Returns void
Destroy
ContextInput::Destroy(string $name): void
Pop the context, restoring any previous value. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns void
Get
ContextInput::Get(string $name): mixed
Read the context value. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The context value.
GetOptional
ContextInput::GetOptional(string $name, mixed $default = null): mixed
Read the context value, or return the default when it is not set. Unlike Get, this does not throw when the context is absent.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$default | mixed | The value to return when the context is not set. Defaults to null. |
Returns mixed The context value, or the default.
ContextMutable
Store a value that can be updated. Create starts it with an initial value, Set updates it, Get reads it, and Destroy returns the final value. Nesting is supported by saving and restoring previous values.
Create
ContextMutable::Create(string $name, mixed $value): void
Start a mutable context with an initial value, saving any current value. The caller must call Destroy when finished.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$value | mixed | The initial value. |
Returns void
Destroy
ContextMutable::Destroy(string $name): mixed
Return the final stored value and pop the context, restoring any previous value. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The final value.
Get
ContextMutable::Get(string $name): mixed
Read the current mutable value. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The current value.
Set
ContextMutable::Set(string $name, mixed $value): void
Update the current value in the mutable context. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$value | mixed | The new value. |
Returns void
ContextOutput
An output value that must be set exactly once before it is destroyed. Create marks the context created but unset, Set fills it once, and Destroy returns the set value. Nesting is supported by saving and restoring previous values.
Create
ContextOutput::Create(string $name): void
Start an output context marked created but not yet set, saving any current value. The caller must call Set exactly once, then Destroy.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns void
Destroy
ContextOutput::Destroy(string $name): mixed
Return the value that was set and pop the context, restoring any previous value. Throws when the context is not found or the value was never set.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The value that was set.
Set
ContextOutput::Set(string $name, mixed $value): void
Set the output value. Can be called only once. Throws when the context was not created or has already been set.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$value | mixed | The value to set. |
Returns void
ContextParse
Parse an array one value at a time. Start begins from index zero, Grab and OptionalGrab consume the next value, and Destroy verifies every value was consumed. Nesting is supported by saving and restoring previous parse state.
Destroy
ContextParse::Destroy(string $name): void
Verify every value was grabbed, then pop the context, restoring any previous value. Throws when the context is not found or values remain unconsumed.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns void
Grab
ContextParse::Grab(string $name): mixed
Take the next value from the array and advance the index. Throws when the context is not found or no more values remain.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The next value.
OptionalGrab
ContextParse::OptionalGrab(string $name): mixed
Take the next value from the array and advance the index, or return null when no more values remain. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The next value, or null when there are no more values.
Start
ContextParse::Start(string $name, array $array): void
Start parsing an array from index zero, saving any current value. The caller must call Destroy when finished.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$array | array | The array to parse. |
Returns void
ContextSnapshotData
A captured context state: the contexts map and the stacks behind each name. Returned by Context::Snapshot and accepted by Context::RestoreSnapshot.
Properties
| Property | Type | Description |
|---|---|---|
$contexts | array | The captured contexts map. Defaults to an empty array. |
$stacks | array | The captured stacks for each name. Defaults to an empty array. |
__construct
$snapshot = new ContextSnapshotData(array $contexts = [], array $stacks = [])
Create a snapshot from a contexts map and stacks.
| Name | Type | Description |
|---|---|---|
$contexts | array | The contexts map. Defaults to an empty array. |
$stacks | array | The stacks for each name. Defaults to an empty array. |
Returns ContextSnapshotData
ContextValue
Store, read and destroy a raw value. Works with raw values directly, with nested contexts supported by saving and restoring previous values.
Create
ContextValue::Create(string $name, mixed $value): void
Store a raw value, saving any current value. The caller must call Destroy when finished.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
$value | mixed | The raw value to store. |
Returns void
Destroy
ContextValue::Destroy(string $name): void
Pop the context, restoring any previous value. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns void
Get
ContextValue::Get(string $name): mixed
Read the context value. Throws when the context is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The context value.
GetOptional
ContextValue::GetOptional(string $name): mixed
Read the context value, or return null when it is not found.
| Name | Type | Description |
|---|---|---|
$name | string | The context name. |
Returns mixed The context value, or null when not found.