Documentation

Shell extends Application
in package

Application

The Psy Shell application.

Usage:

$shell = new Shell; $shell->run();

BUFF_PROMPT


    public
    mixed
    BUFF_PROMPT
    = '... '

PROMPT


    public
    mixed
    PROMPT
    = '>>> '

REPLAY


    public
    mixed
    REPLAY
    = '--> '

RETVAL


    public
    mixed
    RETVAL
    = '=> '

VERSION


    public
    mixed
    VERSION
    = 'v0.9.12'

$autoCompleter


    private
        mixed
    $autoCompleter

$autoExit


    private
        mixed
    $autoExit
     = true

$catchExceptions


    private
        mixed
    $catchExceptions
     = true

$cleaner


    private
        mixed
    $cleaner

$code


    private
        mixed
    $code

$codeBuffer


    private
        mixed
    $codeBuffer

$codeBufferOpen


    private
        mixed
    $codeBufferOpen

$codeStack


    private
        mixed
    $codeStack

$commandLoader


    private
        mixed
    $commandLoader

$commands


    private
        mixed
    $commands
     = []

$commandsMatcher


    private
        mixed
    $commandsMatcher

$config


    private
        mixed
    $config

$context


    private
        mixed
    $context

$defaultCommand


    private
        mixed
    $defaultCommand

$definition


    private
        mixed
    $definition

$dispatcher


    private
        mixed
    $dispatcher

$helperSet


    private
        mixed
    $helperSet

$includes


    private
        mixed
    $includes

$initialized


    private
        mixed
    $initialized

$inputBuffer


    private
        mixed
    $inputBuffer

$lastExecSuccess


    private
        mixed
    $lastExecSuccess
     = true

$loop


    private
        mixed
    $loop

$loopListeners


    private
        mixed
    $loopListeners

$matchers


    private
        mixed
    $matchers
     = []

$name


    private
        mixed
    $name

$output


    private
        mixed
    $output

$outputWantsNewline


    private
        mixed
    $outputWantsNewline
     = false

$prompt


    private
        mixed
    $prompt

$readline


    private
        mixed
    $readline

$runningCommand


    private
        mixed
    $runningCommand

$singleCommand


    private
        mixed
    $singleCommand
     = false

$stdoutBuffer


    private
        mixed
    $stdoutBuffer

$terminal


    private
        mixed
    $terminal

$version


    private
        mixed
    $version

$wantHelps


    private
        mixed
    $wantHelps
     = false

__construct()

Create a new Psy Shell.


    public
                __construct([Configuration $config = null ]) : mixed

Parameters

$config : Configuration = null: (default: null)

Return values

mixed —

add()

Adds a command object.


    public
                add(Command $command) : Command

Parameters

$command : Command: A Symfony Console Command object

Return values

Command —

The registered command

addCode()

Add code to the code buffer.


    public
                addCode(string $code[, bool $silent = false ]) : mixed

Parameters

$code : string
$silent : bool = false

Return values

mixed —

addCommands()

Adds an array of command objects.


    public
                addCommands(array<string|int, Command> $commands) : mixed

If a Command is not enabled it will not be added.

Parameters

$commands : array<string|int, Command>: An array of commands

Return values

mixed —

addInput()

Inject input into the input buffer.


    public
                addInput(string|array<string|int, mixed> $input[, bool $silent = false ]) : mixed

This is useful for commands which want to replay history.

Parameters

$input : string|array<string|int, mixed>
$silent : bool = false

Return values

mixed —

addMatchers()

Add tab completion matchers.


    public
                addMatchers(array<string|int, mixed> $matchers) : mixed

Parameters

$matchers : array<string|int, mixed>

Return values

mixed —

addTabCompletionMatchers()


    public
                addTabCompletionMatchers(array<string|int, mixed> $matchers) : mixed

Parameters

$matchers : array<string|int, mixed>

Return values

mixed —

afterLoop()

Run execution loop listeners after each loop.


    public
                afterLoop() : mixed

Return values

mixed —

all()

Gets the commands (registered in the given namespace if provided).


    public
                all([string $namespace = null ]) : array<string|int, Command>

The array keys are the full names and the values the command instances.

Parameters

$namespace : string = null: A namespace name

Return values

array<string|int, Command> —

An array of Command instances

areExceptionsCaught()

Gets whether to catch exceptions or not during commands execution.


    public
                areExceptionsCaught() : bool

Return values

bool —

Whether to catch exceptions or not during commands execution

beforeLoop()

Run execution loop listeners at the start of each loop.


    public
                beforeLoop() : mixed

Return values

mixed —

debug()

Invoke a Psy Shell from the current context.


    public
            static    debug([array<string|int, mixed> $vars = [] ][, object|string $bindTo = null ]) : array<string|int, mixed>

Parameters

$vars : array<string|int, mixed> = []: Scope variables from the calling context (default: array())
$bindTo : object|string = null: Bound object ($this) or class (self) value for the shell

Return values

array<string|int, mixed> —

Scope variables from the debugger session

doRun()

Runs the current application.


    public
                doRun(InputInterface $input, OutputInterface $output) : int

Parameters

$input : InputInterface: An Input instance
$output : OutputInterface: An Output instance

Return values

int —

0 if everything went fine, or an error code

execute()

Execute code in the shell execution context.


    public
                execute(string $code[, bool $throwExceptions = false ]) : mixed

Parameters

$code : string
$throwExceptions : bool = false

Return values

mixed —

extractNamespace()

Returns the namespace part of the command name.


    public
                extractNamespace(string $name[, string $limit = null ]) : string

This method is not part of public API and should not be used directly.

Parameters

$name : string: The full name of the command
$limit : string = null: The maximum number of parts of the namespace

Return values

string —

The namespace of the command

find()

Finds a command by name or alias.


    public
                find(string $name) : Command

Contrary to get, this command tries to find the best match if you give it an abbreviation of a name or alias.

Parameters

$name : string: A command name or a command alias

Return values

Command —

A Command instance

findNamespace()

Finds a registered namespace by a name or an abbreviation.


    public
                findNamespace(string $namespace) : string

Parameters

$namespace : string: A namespace or abbreviation to search for

Return values

string —

A registered namespace

flushCode()

Flush the current (valid) code buffer.


    public
                flushCode() : string

If the code buffer is valid, resets the code buffer and returns the current code.

Return values

string —

PHP code buffer contents

formatException()

Helper for formatting an exception for writeException().


    public
                formatException(Exception $e) : string

Parameters

$e : Exception

Return values

string —

get()

Returns a registered command by name or alias.


    public
                get(string $name) : Command

Parameters

$name : string: The command name or alias

Return values

Command —

A Command object

getAbbreviations()

Returns an array of possible abbreviations given a set of names.


    public
            static    getAbbreviations(array<string|int, mixed> $names) : array<string|int, mixed>

Parameters

$names : array<string|int, mixed>: An array of names

Return values

array<string|int, mixed> —

An array of abbreviations

getBoundClass()

Get the bound class (self) for the interactive shell.


    public
                getBoundClass() : string|null

Return values

string|null —

getBoundObject()

Get the bound object ($this variable) for the interactive shell.


    public
                getBoundObject() : object|null

Return values

object|null —

getCodeBuffer()

Get the current code buffer.


    public
                getCodeBuffer() : array<string|int, mixed>

This is useful for commands which manipulate the buffer.

Return values

array<string|int, mixed> —

getDefinition()

Gets the InputDefinition related to this Application.


    public
                getDefinition() : InputDefinition

Return values

InputDefinition —

The InputDefinition instance

getHelp()

Gets the help message.


    public
                getHelp() : string

Return values

string —

A help message

getHelperSet()

Get the helper set associated with the command.


    public
                getHelperSet() : HelperSet

Return values

HelperSet —

The HelperSet instance associated with this command

getIncludes()

Get PHP files to be parsed and executed before running the interactive shell.


    public
                getIncludes() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getInput()

Read user input.


    public
                getInput() : mixed

This will continue fetching user input until the code buffer contains valid code.

Return values

mixed —

getLastExecSuccess()

Check whether the last exec was successful.


    public
                getLastExecSuccess() : bool

Returns true if a return value was logged rather than an exception.

Return values

bool —

getLongVersion()

Returns the long version of the application.


    public
                getLongVersion() : string

Return values

string —

The long application version

getManualDb()

Get a PHP manual database instance.


    public
                getManualDb() : PDO|null

Return values

PDO|null —

getName()

Gets the name of the application.


    public
                getName() : string

Return values

string —

The application name

getNamespace()

Get the current evaluation scope namespace.


    public
                getNamespace() : string

Return values

string —

Current code namespace

getNamespaces()

Returns an array of all unique namespaces used by currently registered commands.


    public
                getNamespaces() : array<string|int, string>

It does not return the global namespace which always exists.

Return values

array<string|int, string> —

An array of namespaces

getScopeVariable()

Get a scope variable value by name.


    public
                getScopeVariable(string $name) : mixed

Parameters

$name : string

Return values

mixed —

getScopeVariableNames()

Get the set of variable names currently in scope.


    public
                getScopeVariableNames() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Array of variable names

getScopeVariables()

Return the set of variables currently in scope.


    public
                getScopeVariables([bool $includeBoundObject = true ]) : array<string|int, mixed>

Parameters

$includeBoundObject : bool = true: Pass false to exclude 'this'. If you're passing the scope variables to extract in PHP 7.1+, you must exclude 'this'

Return values

array<string|int, mixed> —

Associative array of scope variables

getScopeVariablesDiff()

Return the set of variables currently in scope which differ from the values passed as $currentVars.


    public
                getScopeVariablesDiff(array<string|int, mixed> $currentVars) : array<string|int, mixed>

This is used inside the Execution Loop Closure to pick up scope variable changes made by commands while the loop is running.

Parameters

$currentVars : array<string|int, mixed>

Return values

array<string|int, mixed> —

Associative array of scope variables which differ from $currentVars

getSpecialScopeVariables()

Return the set of magic variables currently in scope.


    public
                getSpecialScopeVariables([bool $includeBoundObject = true ]) : array<string|int, mixed>

Parameters

$includeBoundObject : bool = true: Pass false to exclude 'this'. If you're passing the scope variables to extract in PHP 7.1+, you must exclude 'this'

Return values

array<string|int, mixed> —

Associative array of magic scope variables

getTerminalDimensions()

Tries to figure out the terminal dimensions based on the current environment.


    public
                getTerminalDimensions() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Array containing width and height

getUnusedCommandScopeVariableNames()

Get the set of unused command-scope variable names.


    public
                getUnusedCommandScopeVariableNames() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Array of unused variable names

getVersion()

Get the current version of Psy Shell.


    public
                getVersion() : string

Return values

string —

handleError()

Helper for throwing an ErrorException.


    public
                handleError(int $errno, string $errstr, string $errfile, int $errline) : mixed

This allows us to:

set_error_handler(array($psysh, 'handleError'));

Unlike ErrorException::throwException, this error handler respects the current error_reporting level; i.e. it logs warnings and notices, but doesn't throw an exception unless it's above the current error_reporting threshold. This should probably only be used in the inner execution loop of the shell, as most of the time a thrown exception is much more useful.

If the error type matches the errorLoggingLevel config, it will be logged as well, regardless of the error_reporting level.

Parameters

$errno : int: Error type
$errstr : string: Message
$errfile : string: Filename
$errline : int: Line number

Return values

mixed —

has()

Returns true if the command exists, false otherwise.


    public
                has(string $name) : bool

Parameters

$name : string: The command name or alias

Return values

bool —

true if the command exists, false otherwise

hasCode()

Check whether this shell's code buffer contains code.


    public
                hasCode() : bool

Return values

bool —

True if the code buffer contains code

isAutoExitEnabled()

Gets whether to automatically exit after a command execution or not.


    public
                isAutoExitEnabled() : bool

Return values

bool —

Whether to automatically exit after a command execution or not

isIncluded()

Check whether the first thing in a backtrace is an include call.


    public
            static    isIncluded(array<string|int, mixed> $trace) : mixed

This is used by the psysh bin to decide whether to start a shell on boot, or to simply autoload the library.

Parameters

$trace : array<string|int, mixed>

Return values

mixed —

onExecute()

Run execution loop listeners on code to be executed.


    public
                onExecute(string $code) : string

Parameters

$code : string

Return values

string —

onInput()

Run execution loop listeners on user input.


    public
                onInput(string $input) : string

Parameters

$input : string

Return values

string —

register()

Registers a new command.


    public
                register(string $name) : Command

Parameters

$name : string: The command name

Return values

Command —

The newly created command

renderException()

Renders a caught exception.


    public
                renderException(Exception $e, OutputInterface $output) : mixed

Parameters

$e : Exception
$output : OutputInterface

Return values

mixed —

resetCodeBuffer()

Reset the current code buffer.


    public
                resetCodeBuffer() : mixed

This should be run after evaluating user input, catching exceptions, or on demand by commands such as BufferCommand.

Return values

mixed —

run()

Runs the current application.


    public
                run([InputInterface $input = null ][, OutputInterface $output = null ]) : int

Parameters

$input : InputInterface = null: An Input instance
$output : OutputInterface = null: An Output instance

Return values

int —

0 if everything went fine, or an error code

setAutoExit()

Sets whether to automatically exit after a command execution or not.


    public
                setAutoExit(bool $boolean) : mixed

Parameters

$boolean : bool: Whether to automatically exit after a command execution or not

Return values

mixed —

setBoundClass()

Set the bound class (self) for the interactive shell.


    public
                setBoundClass(string|null $boundClass) : mixed

Parameters

$boundClass : string|null

Return values

mixed —

setBoundObject()

Set the bound object ($this variable) for the interactive shell.


    public
                setBoundObject(object|null $boundObject) : mixed

Parameters

$boundObject : object|null

Return values

mixed —

setCatchExceptions()

Sets whether to catch exceptions or not during commands execution.


    public
                setCatchExceptions(bool $boolean) : mixed

Parameters

$boolean : bool: Whether to catch exceptions or not during commands execution

Return values

mixed —

setCommandLoader()


    public
                setCommandLoader(CommandLoaderInterface $commandLoader) : mixed

Parameters

$commandLoader : CommandLoaderInterface

Return values

mixed —

setDefaultCommand()

Sets the default Command name.


    public
                setDefaultCommand(string $commandName[, bool $isSingleCommand = false ]) : self

Parameters

$commandName : string: The Command name
$isSingleCommand : bool = false: Set to true if there is only one command in this application

Return values

self —

setDefinition()


    public
                setDefinition(InputDefinition $definition) : mixed

Parameters

$definition : InputDefinition

Return values

mixed —

setDispatcher()


    public
                setDispatcher(EventDispatcherInterface $dispatcher) : mixed

Parameters

$dispatcher : EventDispatcherInterface

Return values

mixed —

setHelperSet()


    public
                setHelperSet(HelperSet $helperSet) : mixed

Parameters

$helperSet : HelperSet

Return values

mixed —

setIncludes()

Add includes, to be parsed and executed before running the interactive shell.


    public
                setIncludes([array<string|int, mixed> $includes = [] ]) : mixed

Parameters

$includes : array<string|int, mixed> = []

Return values

mixed —

setName()

Sets the application name.


    public
                setName(string $name) : mixed

Parameters

$name : string: The application name

Return values

mixed —

setOutput()

Set the Shell output.


    public
                setOutput(OutputInterface $output) : mixed

Parameters

$output : OutputInterface

Return values

mixed —

setScopeVariables()

Set the variables currently in scope.


    public
                setScopeVariables(array<string|int, mixed> $vars) : mixed

Parameters

$vars : array<string|int, mixed>

Return values

mixed —

setTerminalDimensions()

Sets terminal dimensions.


    public
                setTerminalDimensions(int $width, int $height) : $this

Can be useful to force terminal dimensions for functional tests.

Parameters

$width : int: The width
$height : int: The height

Return values

$this —

setVersion()

Sets the application version.


    public
                setVersion(string $version) : mixed

Parameters

$version : string: The application version

Return values

mixed —

writeException()

Renders a caught Exception.


    public
                writeException(Exception $e) : mixed

Exceptions are formatted according to severity. ErrorExceptions which were warnings or Strict errors aren't rendered as harshly as real errors.

Stores $e as the last Exception in the Shell Context.

Parameters

$e : Exception: An exception instance

Return values

mixed —

writeReturnValue()

Write a return value to stdout.


    public
                writeReturnValue(mixed $ret) : mixed

The return value is formatted or pretty-printed, and rendered in a visibly distinct manner (in this case, as cyan).

Parameters

$ret : mixed

Return values

mixed —

writeStdout()

Write a string to stdout.


    public
                writeStdout(string $out[, int $phase = PHP_OUTPUT_HANDLER_END ]) : mixed

This is used by the shell loop for rendering output from evaluated code.

Parameters

$out : string
$phase : int = PHP_OUTPUT_HANDLER_END: Output buffering phase

Return values

mixed —

afterRun()

Run execution loop listers after the shell session.


    protected
                afterRun() : mixed

Return values

mixed —

autocomplete()


    protected
                autocomplete(mixed $text) : mixed

Parameters

$text : mixed

Return values

mixed —

beforeRun()

Run execution loop listeners before the shell session.


    protected
                beforeRun() : mixed

Return values

mixed —

configureIO()

Configures the input and output instances based on the user arguments and options.


    protected
                configureIO(InputInterface $input, OutputInterface $output) : mixed

Parameters

$input : InputInterface
$output : OutputInterface

Return values

mixed —

doRenderException()


    protected
                doRenderException(Exception $e, OutputInterface $output) : mixed

Parameters

$e : Exception
$output : OutputInterface

Return values

mixed —

doRunCommand()

Runs the current command.


    protected
                doRunCommand(Command $command, InputInterface $input, OutputInterface $output) : int

If an event dispatcher has been attached to the application, events are also dispatched during the life-cycle of the command.

Parameters

$command : Command
$input : InputInterface
$output : OutputInterface

Return values

int —

0 if everything went fine, or an error code

getCommand()

Get a command (if one exists) for the current input string.


    protected
                getCommand(string $input) : null|Command

Parameters

$input : string

Return values

null|Command —

getCommandName()

Gets the name of the command based on input.


    protected
                getCommandName(InputInterface $input) : string|null

Parameters

$input : InputInterface

Return values

string|null —

getDefaultCommands()

Gets the default commands that should always be available.


    protected
                getDefaultCommands() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of default Command instances

getDefaultHelperSet()

Gets the default helper set with the helpers that should always be available.


    protected
                getDefaultHelperSet() : HelperSet

Return values

HelperSet —

A HelperSet instance

getDefaultInputDefinition()

Gets the default input definition.


    protected
                getDefaultInputDefinition() : InputDefinition

Return values

InputDefinition —

An InputDefinition instance

getDefaultLoopListeners()

Gets the default command loop listeners.


    protected
                getDefaultLoopListeners() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of Execution Loop Listener instances

getDefaultMatchers()


    protected
                getDefaultMatchers() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getHeader()

Get the shell output header.


    protected
                getHeader() : string

Return values

string —

getPrompt()

Get the current input prompt.


    protected
                getPrompt() : string

Return values

string —

getSeverity()

Helper for getting an output style for the given ErrorException's level.


    protected
                getSeverity(ErrorException $e) : string

Parameters

$e : ErrorException

Return values

string —

getTabCompletionMatchers()


    protected
                getTabCompletionMatchers() : mixed

Return values

mixed —

getTerminalHeight()

Tries to figure out the terminal height in which this application runs.


    protected
                getTerminalHeight() : int|null

Return values

int|null —

getTerminalWidth()

Tries to figure out the terminal width in which this application runs.


    protected
                getTerminalWidth() : int|null

Return values

int|null —

hasCommand()

Check whether a command is set for the current input string.


    protected
                hasCommand(string $input) : bool

Parameters

$input : string

Return values

bool —

True if the shell has a command for the given input

hasValidCode()

Check whether the code in this shell's code buffer is valid.


    protected
                hasValidCode() : bool

If the code is valid, the code buffer should be flushed and evaluated.

Return values

bool —

True if the code buffer content is valid

initializeTabCompletion()

Initialize tab completion matchers.


    protected
                initializeTabCompletion() : mixed

If tab completion is enabled this adds tab completion matchers to the auto completer and sets context if needed.

Return values

mixed —

presentValue()

Format a value for display.


    protected
                presentValue(mixed $val) : string

Parameters

$val : mixed

Return values

string —

Formatted value

readline()

Read a line of user input.


    protected
                readline() : string

This will return a line from the input buffer (if any exist). Otherwise, it will ask the user for input.

If readline is enabled, this delegates to readline. Otherwise, it's an ugly fgets call.

Return values

string —

One line of user input

runCommand()

Run a Psy Shell command given the user input.


    protected
                runCommand(string $input) : mixed

Parameters

$input : string: User input string

Return values

mixed —

Who knows?

writeStartupMessage()

Write a startup message if set.


    protected
                writeStartupMessage() : mixed

Return values

mixed —

writeVersionInfo()


    protected
                writeVersionInfo() : void|string

Return values

void|string —

addCodeBufferToHistory()

Filter silent input from code buffer, write the rest to readline history.


    private
                addCodeBufferToHistory() : mixed

Return values

mixed —

addHistory()

(Possibly) add a line to the readline history.


    private
                addHistory(string|SilentInput $line) : mixed

Like Bash, if the line starts with a space character, it will be omitted from history. Note that an entire block multi-line code input will be omitted iff the first line begins with a space.

Additionally, if a line is "silent", i.e. it was initially added with the silent flag, it will also be omitted.

Parameters

$line : string|SilentInput

Return values

mixed —

addMatchersToAutoCompleter()

Add matchers to the auto completer, setting context if needed.


    private
                addMatchersToAutoCompleter(array<string|int, mixed> $matchers) : mixed

Parameters

$matchers : array<string|int, mixed>

Return values

mixed —

extractAllNamespaces()

Returns all namespaces of the command name.


    private
                extractAllNamespaces(string $name) : array<string|int, string>

Parameters

$name : string: The full name of the command

Return values

array<string|int, string> —

The namespaces of the command

findAlternatives()

Finds alternative of $name among $collection, if nothing is found in $collection, try in $abbrevs.


    private
                findAlternatives(string $name, iteratable<string|int, mixed> $collection) : array<string|int, string>

Parameters

$name : string: The string
$collection : iteratable<string|int, mixed>: The collection

Return values

array<string|int, string> —

A sorted array of similar string

getAbbreviationSuggestions()

Returns abbreviated suggestions in string format.


    private
                getAbbreviationSuggestions(array<string|int, mixed> $abbrevs) : string

Parameters

$abbrevs : array<string|int, mixed>: Abbreviated suggestions to convert

Return values

string —

A formatted string of abbreviated suggestions

init()


    private
                init() : mixed

Return values

mixed —

inputInOpenStringOrComment()

Check whether the code buffer (plus current input) is in an open string or comment.


    private
                inputInOpenStringOrComment(string $input) : bool

Parameters

$input : string: current line of input

Return values

bool —

true if the input is in an open string or comment

popCodeStack()

Reset the code buffer and restore any code pushed during `execute` calls.


    private
                popCodeStack() : mixed

Return values

mixed —

setCode()

Set the code buffer.


    private
                setCode(string $code[, bool $silent = false ]) : mixed

This is mostly used by Shell::execute. Any existing code in the input buffer is pushed onto a stack and will come back after this new code is executed.

Parameters

$code : string
$silent : bool = false

Return values

mixed —

splitStringByWidth()


    private
                splitStringByWidth(mixed $string, mixed $width) : mixed

Parameters

$string : mixed
$width : mixed

Return values

mixed —