Skip to main content
The Shell execution context. Encapsulates current variables, most recent return value and exception, and bound object/class.

​
Constructor

​
__construct()

Create a new Context instance. 
use Psy\Context;

$context = new Context();

​
Variable Management

​
get(string $name): mixed

Get a context variable by name.
​
name
string
required
Variable name (without $)
​
return
mixed
Variable value
$context->setAll(['foo' => 'bar']);
$value = $context->get('foo'); // 'bar'

// Special variables
$returnValue = $context->get('_');
$lastException = $context->get('_e');
$lastOutput = $context->get('__out');
$boundObject = $context->get('this');
Throws: InvalidArgumentException if the variable is not found.

​
getAll(): array

Get all defined variables. Includes both regular scope variables and magic variables (_,\_, _e, __out,\_\_out, this, etc.).
​
return
array
Associative array of all variables
$allVars = $context->getAll();

​
getSpecialVariables(): array

Get all defined magic variables: _,\_, _e, __out,\_\_out, __class, $__file, etc.
​
return
array
Associative array of magic variables
$specialVars = $context->getSpecialVariables();
// ['_' => ..., '_e' => ..., '__out' => ..., 'this' => ...]

​
setAll(array $vars): void

Set all scope variables. This method does not set magic variables (_,\_, _e, __out,\_\_out, __class, etc.).
​
vars
array
required
Associative array of variable names to values
$context->setAll([
    'foo' => 'bar',
    'items' => [1, 2, 3],
    'user' => $userObject,
]);

​
Return Value

​
setReturnValue($value): void

Set the most recent return value. This value is available as the $_ magic variable.
​
value
mixed
required
Return value to store
$context->setReturnValue(42);
$value = $context->get('_'); // 42

​
getReturnValue(): mixed

Get the most recent return value.
​
return
mixed
Most recent return value
$lastReturn = $context->getReturnValue();

​
Exception Handling

​
setLastException(Throwable $e): void

Set the most recent exception or error. This value is available as the $_e magic variable.
​
e
Throwable
required
Exception or error to store
try {
    // some code
} catch (\Exception $e) {
    $context->setLastException($e);
}

​
getLastException(): ?Throwable

Get the most recent exception or error.
​
return
Throwable|null
Most recent exception, or null
$lastException = $context->getLastException();
Throws: InvalidArgumentException if no exception has been caught.

​
Output Capturing

​
setLastStdout(string $lastStdout): void

Set the most recent output from evaluated code. This value is available as the $__out magic variable.
​
lastStdout
string
required
Output string to store
$context->setLastStdout('Hello, world!');
$output = $context->get('__out'); // 'Hello, world!'

​
getLastStdout(): ?string

Get the most recent output from evaluated code.
​
return
string|null
Most recent output, or null
$lastOutput = $context->getLastStdout();
Throws: InvalidArgumentException if no output has happened yet.

​
Object and Class Binding

​
setBoundObject($boundObject): void

Set the bound object ($this variable) for the interactive shell. This makes the object available as $this in the REPL, allowing access to private and protected members. Note: This unsets the bound class, if any exists.
​
boundObject
object|null
required
Object to bind, or null to unbind
class MyClass {
    private $secret = 'hidden';
}

$obj = new MyClass();
$context->setBoundObject($obj);
// Now $this->secret is accessible in the shell

​
getBoundObject(): ?object

Get the bound object ($this variable) for the interactive shell.
​
return
object|null
Bound object, or null
$boundObj = $context->getBoundObject();

​
setBoundClass($boundClass): void

Set the bound class (self) for the interactive shell. This makes the class available as self in the REPL, allowing access to private and protected static members. Note: This unsets the bound object, if any exists.
​
boundClass
string|null
required
Fully qualified class name, or null to unbind
$context->setBoundClass('App\\MyClass');
// Now self::$staticProperty is accessible in the shell

​
getBoundClass(): ?string

Get the bound class (self) for the interactive shell.
​
return
string|null
Bound class name, or null
$boundClass = $context->getBoundClass();

​
Command Scope Variables

​
setCommandScopeVariables(array $commandScopeVariables): void

Set command-scope magic variables: __class,\_\_class, __file, $__method, etc. These are typically set by PsySH commands like whereami and show.
​
commandScopeVariables
array
required
Array of command scope variables
$context->setCommandScopeVariables([
    '__class' => 'App\\MyClass',
    '__method' => 'myMethod',
    '__file' => '/path/to/file.php',
    '__line' => 42,
]);

​
getCommandScopeVariables(): array

Get command-scope magic variables.
​
return
array
Array of command scope variables
$commandVars = $context->getCommandScopeVariables();

​
getUnusedCommandScopeVariableNames(): array

Get unused command-scope magic variable names. This is used by the shell to unset old command-scope variables after a new batch is set.
​
return
array
Array of unused variable names
$unusedNames = $context->getUnusedCommandScopeVariableNames();

​
Static Methods

​
isSpecialVariableName(string $name): bool

Check whether a variable name is a magic variable.
​
name
string
required
Variable name (without $)
​
return
bool
True if the name is a special/magic variable
$isSpecial = Context::isSpecialVariableName('_'); // true
$isSpecial = Context::isSpecialVariableName('_e'); // true
$isSpecial = Context::isSpecialVariableName('foo'); // false

​
Magic Variables

The Context class manages these special variables:
VariableDescription
$_Most recent return value
$_eMost recent exception
$__outMost recent stdout output
$thisBound object
$__functionCurrent function name (command scope)
$__methodCurrent method name (command scope)
$__classCurrent class name (command scope)
$__namespaceCurrent namespace (command scope)
$__fileCurrent file path (command scope)
$__lineCurrent line number (command scope)
$__dirCurrent directory (command scope)

​
Usage Example

use Psy\Context;

$context = new Context();

// Set up scope variables
$context->setAll([
    'app' => $application,
    'db' => $database,
    'user' => $currentUser,
]);

// Bind an object for $this access
$context->setBoundObject($myObject);

// Simulate code execution
$context->setReturnValue(42);
$context->setLastStdout('Hello, world!');

// Access variables
$allVars = $context->getAll();
// [
//     'app' => ...,
//     'db' => ...,
//     'user' => ...,
//     '_' => 42,
//     '__out' => 'Hello, world!',
//     'this' => ...,
// ]

// Get specific values
$returnValue = $context->getReturnValue(); // 42
$output = $context->getLastStdout(); // 'Hello, world!'

Build docs developers (and LLMs) love

Get started for freeTalk to us