\Psy\Configuration

The PsySH Shell configuration class. Controls shell behavior, appearance, and features.

Constructor

`__construct(array $config = [])`

Construct a Configuration instance. Optionally supply an array of configuration values to load.

config

array

Array of configuration options

use Psy\Configuration;

// Default configuration
$config = new Configuration();

// Custom configuration
$config = new Configuration([
    'colorMode' => 'forced',
    'defaultIncludes' => ['/path/to/bootstrap.php'],
    'requireSemicolons' => true,
    'useUnicode' => true,
]);

Static Methods

`fromInput(InputInterface $input): self`

Construct a Configuration object from Symfony Console input. Great for adding psysh-compatible command line options to framework- or app-specific wrappers.

input

InputInterface

required

Symfony Console input (should be bound to an InputDefinition first)

return

Configuration

Configuration instance

use Symfony\Component\Console\Input\ArgvInput;
use Psy\Configuration;

$input = new ArgvInput();
$config = Configuration::fromInput($input);

`getInputOptions(): array`

Get a list of input options expected when initializing Configuration via input.

return

InputOption[]

Array of Symfony Console InputOption instances

use Symfony\Component\Console\Input\InputDefinition;
use Psy\Configuration;

$definition = new InputDefinition(Configuration::getInputOptions());

Configuration Methods

`loadConfig(array $options): void`

Load configuration values from an array of options.

options

array

required

Configuration options

$config->loadConfig([
    'colorMode' => 'forced',
    'requireSemicolons' => true,
]);

`loadConfigFile(string $file): void`

Load a configuration file (default: ~/.config/psysh/config.php). The configuration instance is available to the config file as $config. The config file may directly manipulate the configuration, or return an array of options.

file

string

required

Path to configuration file

$config->loadConfigFile('/path/to/config.php');

`init(): void`

Initialize the configuration. Checks for Readline and Pcntl extensions. Loads config files if available.

File and Directory Methods

`getConfigFile(): ?string`

Get the current PsySH config file. Searches for config.php or rc.php in config directories.

return

string|null

Config file path, or null if none exists

`getLocalConfigFile(): ?string`

Get the local PsySH config file (.psysh.php in current working directory).

return

string|null

Local config file path, or null

`setConfigDir(string $dir): void`

Set the shell’s config directory location.

dir

string

required

Config directory path

`getConfigDir(): ?string`

Get the current configuration directory.

return

string|null

Config directory path, or null

`setDataDir(string $dir): void`

Set the shell’s data directory location.

dir

string

required

Data directory path

`getDataDir(): ?string`

Get the current data directory.

return

string|null

Data directory path, or null

`setRuntimeDir(string $dir): void`

Set the shell’s temporary directory location.

dir

string

required

Runtime directory path

`getRuntimeDir(bool $create = true): string`

Get the shell’s temporary directory location. Defaults to /psysh inside the system’s temp dir.

create

bool

default:"true"

Whether to create directory if it doesn’t exist

return

string

Runtime directory path

History Configuration

`setHistoryFile(string $file): void`

Set the readline history file path.

file

string

required

History file path

`getHistoryFile(): ?string`

Get the readline history file path. Defaults to /history inside the shell’s config dir.

return

string|null

History file path, or null

`setHistorySize(int $value): void`

Set the readline max history size.

value

int

required

Maximum history entries

`getHistorySize(): int`

Get the readline max history size.

return

int

Maximum history entries (0 = unlimited)

`setEraseDuplicates(bool $value): void`

Set whether readline erases old duplicate history entries.

value

bool

required

Whether to erase duplicates

`getEraseDuplicates(): ?bool`

Get whether readline erases old duplicate history entries.

return

bool|null

True if duplicates are erased, null if not set

Includes

`setDefaultIncludes(array $includes = []): void`

Set files to be included by default at the start of each shell session.

includes

array

default:"[]"

Array of file paths

$config->setDefaultIncludes([
    '/path/to/bootstrap.php',
    '/path/to/helpers.php',
]);

`getDefaultIncludes(): array`

Get files to be included by default at the start of each shell session.

return

string[]

Array of file paths

Readline Configuration

`hasReadline(): bool`

Check whether this PHP instance has Readline available.

return

bool

True if Readline is available

`setUseReadline(bool $useReadline): void`

Enable or disable Readline usage.

useReadline

bool

required

Whether to use Readline

`useReadline(): bool`

Check whether to use Readline.

return

bool

True if Readline should be used

`setReadline(Readline\Readline $readline): void`

Set the PsySH readline service.

readline

Readline\Readline

required

Readline instance

`getReadline(): Readline\Readline`

Get the PsySH readline service. By default uses GNU Readline, Libedit, or array-based emulation.

return

Readline\Readline

Readline instance

`setUseBracketedPaste(bool $useBracketedPaste): void`

Enable or disable bracketed paste. Only works with GNU readline (not libedit).

useBracketedPaste

bool

required

Whether to use bracketed paste

`useBracketedPaste(): bool`

Check whether to use bracketed paste with readline.

return

bool

True if bracketed paste should be used

Pcntl Configuration

`hasPcntl(): bool`

Check whether this PHP instance has Pcntl available.

return

bool

True if Pcntl is available

`setUsePcntl(bool $usePcntl): void`

Enable or disable Pcntl usage.

usePcntl

bool

required

Whether to use Pcntl

`usePcntl(): bool`

Check whether to use Pcntl.

return

bool

True if Pcntl should be used

Output Configuration

`setOutput(ShellOutput $output): void`

Set the Shell Output service.

output

ShellOutput

required

Output instance

`getOutput(): ShellOutput`

Get a Shell Output service instance.

return

ShellOutput

Output instance

`setRawOutput(bool $rawOutput): void`

Enable or disable raw output.

rawOutput

bool

required

Whether to use raw output

`rawOutput(): bool`

Check whether to use raw output (var_export style). Set by --raw-output flag, only makes sense when non-interactive.

return

bool

True if raw output is enabled

Set the OutputPager service. Can be a string (command name) or OutputPager instance. Use ‘cat’ or false to disable.

Pager command or instance

$config->setPager('less -R');
$config->setPager(false); // disable paging

`getPager(): string|OutputPager|false`

Get an OutputPager instance or command for an external pager.

return

string|OutputPager|false

Pager command, instance, or false if disabled

Color and Theme Configuration

`setColorMode(string $colorMode): void`

Set the current color mode.

colorMode

string

required

One of: ‘auto’, ‘forced’, ‘disabled’

use Psy\Configuration;

$config->setColorMode(Configuration::COLOR_MODE_FORCED);
$config->setColorMode(Configuration::COLOR_MODE_DISABLED);
$config->setColorMode(Configuration::COLOR_MODE_AUTO);

`colorMode(): string`

Get the current color mode.

return

string

One of: ‘auto’, ‘forced’, ‘disabled’

`setTheme($theme): void`

Set the current output Theme.

theme

Theme|string|array

required

Theme instance, name, or config array

// Use built-in theme
$config->setTheme('compact');

// Custom theme
$config->setTheme(new Theme([
    'prompt' => '\\> ',
    'compact' => true,
]));

`theme(): Theme`

Get the current output Theme.

return

Theme

Theme instance

Interactive Mode

`setInteractiveMode(string $interactiveMode): void`

Set the shell’s interactive mode.

interactiveMode

string

required

One of: ‘auto’, ‘forced’, ‘disabled’

use Psy\Configuration;

$config->setInteractiveMode(Configuration::INTERACTIVE_MODE_FORCED);
$config->setInteractiveMode(Configuration::INTERACTIVE_MODE_DISABLED);

`interactiveMode(): string`

Get the current interactive mode.

return

string

One of: ‘auto’, ‘forced’, ‘disabled’

`getInputInteractive(): bool`

Get whether shell input is interactive.

return

bool

True if input is interactive

Verbosity

`setVerbosity(string $verbosity): void`

Set the shell output verbosity.

verbosity

string

required

One of: ‘quiet’, ‘normal’, ‘verbose’, ‘very_verbose’, ‘debug’

use Psy\Configuration;

$config->setVerbosity(Configuration::VERBOSITY_DEBUG);
$config->setVerbosity(Configuration::VERBOSITY_QUIET);

`verbosity(): string`

Get the configured output verbosity.

return

string

One of: ‘quiet’, ‘normal’, ‘verbose’, ‘very_verbose’, ‘debug’

`getOutputVerbosity(): int`

Map the verbosity configuration to OutputInterface verbosity constants.

return

int

Symfony Console OutputInterface verbosity level

Code Execution Configuration

`setRequireSemicolons(bool $requireSemicolons): void`

Enable or disable strict requirement of semicolons.

requireSemicolons

bool

required

Whether to require semicolons

`requireSemicolons(): bool`

Check whether to require semicolons on all statements. By default, PsySH will automatically insert semicolons if missing.

return

bool

True if semicolons are required

`setStrictTypes(bool $strictTypes): void`

Enable or disable strict types enforcement.

strictTypes

bool

required

Whether to enforce strict types

`strictTypes(): bool`

Check whether to enforce strict types.

return

bool

True if strict types are enforced

`setYolo(bool $yolo): void`

Enable or disable running PsySH without input validation. You don’t want this.

yolo

bool

required

Whether to disable validation

`yolo(): bool`

Check whether to disable input validation.

return

bool

True if validation is disabled

`setCodeCleaner(CodeCleaner $cleaner): void`

Set a CodeCleaner service instance.

cleaner

CodeCleaner

required

CodeCleaner instance

`getCodeCleaner(): CodeCleaner`

Get a CodeCleaner service instance.

return

CodeCleaner

CodeCleaner instance

Error Handling

`setErrorLoggingLevel(int $errorLoggingLevel): void`

Set the error logging level.

errorLoggingLevel

int

required

Error level bitmask (e.g., E_ALL, E_WARNING)

$config->setErrorLoggingLevel(E_ALL);
$config->setErrorLoggingLevel(E_WARNING | E_NOTICE);
$config->setErrorLoggingLevel(0); // disable error logging

`errorLoggingLevel(): int`

Get the current error logging level. By default, PsySH logs all errors regardless of error_reporting level.

return

int

Error level bitmask

Unicode

`setUseUnicode(bool $useUnicode): void`

Enable or disable Unicode in PsySH specific output.

useUnicode

bool

required

Whether to use Unicode

`useUnicode(): bool`

Check whether to use Unicode in PsySH specific output.

return

bool

True if Unicode should be used

Tab Completion

`setUseTabCompletion(bool $useTabCompletion): void`

Enable or disable tab completion.

useTabCompletion

bool

required

Whether to use tab completion

`useTabCompletion(): bool`

Check whether to use tab completion.

return

bool

True if tab completion should be used

`setAutoCompleter(AutoCompleter $autoCompleter): void`

Set the Shell AutoCompleter service.

autoCompleter

AutoCompleter

required

AutoCompleter instance

`getAutoCompleter(): AutoCompleter`

Get an AutoCompleter service instance.

return

AutoCompleter

AutoCompleter instance

`addMatchers(array $matchers): void`

Add tab completion matchers to the AutoCompleter.

matchers

array

required

Array of matcher instances

Autoload Warming

`setWarmAutoload($config): void`

Configure autoload warming.

config

bool|array

required

False to disable, true for defaults, or array for custom config

// Enable with defaults
$config->setWarmAutoload(true);

// Disable
$config->setWarmAutoload(false);

// Custom configuration
$config->setWarmAutoload([
    'includeVendor' => true,
    'includeNamespaces' => ['App\\'],
    'excludeNamespaces' => ['App\\Legacy\\'],
]);

`getAutoloadWarmers(): array`

Get configured autoload warmers.

return

AutoloadWarmerInterface[]

Array of autoload warmer instances

Implicit Use

`setImplicitUse($config): void`

Set implicit use statement configuration. Automatically adds use statements for unqualified class references.

config

false|array

required

False to disable, or array with includeNamespaces/excludeNamespaces

$config->setImplicitUse([
    'includeNamespaces' => ['App\\', 'Domain\\'],
    'excludeNamespaces' => ['App\\Legacy\\'],
]);

`getImplicitUse(): bool|array`

Get implicit use configuration.

return

bool|array

Implicit use configuration

Logging

`setLogging($logging): void`

Configure logging. Logs PsySH input, commands, and executed code.

logging

LoggerInterface|callable|array

required

PSR-3 logger, callback, or config array

// Simple callback logging
$config->setLogging(function ($kind, $data) {
    file_put_contents('/tmp/psysh.log', "[$kind] $data\n", FILE_APPEND);
});

// PSR-3 logger
$config->setLogging($psrLogger);

// Granular control
$config->setLogging([
    'logger' => $psrLogger,
    'level' => [
        'input' => 'info',
        'command' => false,
        'execute' => 'debug',
    ],
]);

`getLogger(): ?ShellLogger`

Get a ShellLogger instance if logging is configured.

return

ShellLogger|null

Logger instance, or null

Commands and Matchers

`addCommands(array $commands): void`

Add commands to the Shell.

commands

array

required

Array of Command instances

$config->addCommands([
    new MyCustomCommand(),
]);

`setShell(Shell $shell): void`

Set the Shell backreference and add any new commands.

shell

Shell

required

Shell instance

Manual Configuration

`setManualDbFile(string $filename): void`

Set the PHP manual database file.

filename

string

required

Path to manual database file (SQLite or PHP)

`getManualDbFile(): ?string`

Get the current PHP manual database file.

return

string|null

Manual database file path, or null

`getManual(): ?ManualInterface`

Get a PHP manual instance. Automatically detects format (v2 SQLite or v3 PHP).

return

ManualInterface|null

Manual instance, or null if none available

Update Checking

`setUpdateCheck(string $interval): void`

Set the update check interval.

interval

string

required

One of: ‘always’, ‘daily’, ‘weekly’, ‘monthly’, ‘never’

use Psy\VersionUpdater\Checker;

$config->setUpdateCheck(Checker::DAILY);
$config->setUpdateCheck(Checker::NEVER);

`getUpdateCheck(): string`

Get the current update check interval.

return

string

One of: ‘always’, ‘daily’, ‘weekly’, ‘monthly’, ‘never’

`getChecker(): Checker`

Get an update checker service instance.

return

Checker

Update checker instance

Project Trust

`setTrustProject($mode): void`

Configure the project trust mode.

mode

bool|string|null

required

Boolean, or one of: ‘prompt’, ‘always’, ‘never’

use Psy\Configuration;

$config->setTrustProject(true); // always trust
$config->setTrustProject(false); // never trust
$config->setTrustProject(Configuration::PROJECT_TRUST_PROMPT);

`getProjectTrustMode(): string`

Get the current project trust mode.

return

string

One of: ‘prompt’, ‘always’, ‘never’

Constants

COLOR_MODE_AUTO

string

Auto-detect color support (default)

COLOR_MODE_FORCED

string

Force color output

COLOR_MODE_DISABLED

string

Disable color output

INTERACTIVE_MODE_AUTO

string

Auto-detect interactive mode (default)

INTERACTIVE_MODE_FORCED

string

Force interactive mode

INTERACTIVE_MODE_DISABLED

string

Disable interactive mode

PROJECT_TRUST_PROMPT

string

Prompt user for project trust (default)

PROJECT_TRUST_ALWAYS

string

Always trust projects

PROJECT_TRUST_NEVER

string

Never trust projects (restricted mode)

VERBOSITY_QUIET

string

Quiet output level

VERBOSITY_NORMAL

string

Normal output level (default)

VERBOSITY_VERBOSE

string

Verbose output level

VERBOSITY_VERY_VERBOSE

string

Very verbose output level

VERBOSITY_DEBUG

string

Debug output level

Usage Example

use Psy\Configuration;
use Psy\Shell;

$config = new Configuration([
    // Directories
    'configDir' => '/custom/config',
    'dataDir' => '/custom/data',
    
    // Appearance
    'colorMode' => Configuration::COLOR_MODE_FORCED,
    'theme' => 'compact',
    'useUnicode' => true,
    
    // Behavior
    'requireSemicolons' => false,
    'strictTypes' => true,
    'useTabCompletion' => true,
    
    // Files to include on startup
    'defaultIncludes' => [
        __DIR__ . '/bootstrap.php',
    ],
    
    // History
    'historySize' => 5000,
    'eraseDuplicates' => true,
    
    // Autoload warming
    'warmAutoload' => [
        'includeNamespaces' => ['App\\'],
    ],
]);

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

Core Classes

Functions

​Constructor

​__construct(array $config = [])

​Static Methods

​fromInput(InputInterface $input): self

​getInputOptions(): array

​Configuration Methods

​loadConfig(array $options): void

​loadConfigFile(string $file): void

​init(): void

​File and Directory Methods

​getConfigFile(): ?string

​getLocalConfigFile(): ?string

​setConfigDir(string $dir): void

​getConfigDir(): ?string

​setDataDir(string $dir): void

​getDataDir(): ?string

​setRuntimeDir(string $dir): void

​getRuntimeDir(bool $create = true): string

​History Configuration

​setHistoryFile(string $file): void

​getHistoryFile(): ?string

​setHistorySize(int $value): void

​getHistorySize(): int

​setEraseDuplicates(bool $value): void

​getEraseDuplicates(): ?bool

​Includes

​setDefaultIncludes(array $includes = []): void

​getDefaultIncludes(): array

​Readline Configuration

​hasReadline(): bool

​setUseReadline(bool $useReadline): void

​useReadline(): bool

​setReadline(Readline\Readline $readline): void

​getReadline(): Readline\Readline

​setUseBracketedPaste(bool $useBracketedPaste): void

​useBracketedPaste(): bool

​Pcntl Configuration

​hasPcntl(): bool

​setUsePcntl(bool $usePcntl): void

​usePcntl(): bool

​Output Configuration

​setOutput(ShellOutput $output): void

​getOutput(): ShellOutput

​setRawOutput(bool $rawOutput): void

​rawOutput(): bool

​setPager($pager): void

​getPager(): string|OutputPager|false

​Color and Theme Configuration

​setColorMode(string $colorMode): void

​colorMode(): string

​setTheme($theme): void

​theme(): Theme

​Interactive Mode

​setInteractiveMode(string $interactiveMode): void

​interactiveMode(): string

​getInputInteractive(): bool

​Verbosity

​setVerbosity(string $verbosity): void

​verbosity(): string

​getOutputVerbosity(): int

​Code Execution Configuration

​setRequireSemicolons(bool $requireSemicolons): void

​requireSemicolons(): bool

​setStrictTypes(bool $strictTypes): void

​strictTypes(): bool

​setYolo(bool $yolo): void

​yolo(): bool

​setCodeCleaner(CodeCleaner $cleaner): void

​getCodeCleaner(): CodeCleaner

​Error Handling

​setErrorLoggingLevel(int $errorLoggingLevel): void

​errorLoggingLevel(): int

​Unicode

​setUseUnicode(bool $useUnicode): void

​useUnicode(): bool

​Tab Completion

​setUseTabCompletion(bool $useTabCompletion): void

​useTabCompletion(): bool

Constructor

`__construct(array $config = [])`

Static Methods

`fromInput(InputInterface $input): self`

`getInputOptions(): array`

Configuration Methods

`loadConfig(array $options): void`

`loadConfigFile(string $file): void`

`init(): void`

File and Directory Methods

`getConfigFile(): ?string`

`getLocalConfigFile(): ?string`

`setConfigDir(string $dir): void`

`getConfigDir(): ?string`

`setDataDir(string $dir): void`

`getDataDir(): ?string`

`setRuntimeDir(string $dir): void`

`getRuntimeDir(bool $create = true): string`

History Configuration

`setHistoryFile(string $file): void`

`getHistoryFile(): ?string`

`setHistorySize(int $value): void`

`getHistorySize(): int`

`setEraseDuplicates(bool $value): void`

`getEraseDuplicates(): ?bool`

Includes

`setDefaultIncludes(array $includes = []): void`

`getDefaultIncludes(): array`

Readline Configuration

`hasReadline(): bool`

`setUseReadline(bool $useReadline): void`

`useReadline(): bool`

`setReadline(Readline\Readline $readline): void`

`getReadline(): Readline\Readline`

`setUseBracketedPaste(bool $useBracketedPaste): void`

`useBracketedPaste(): bool`

Pcntl Configuration

`hasPcntl(): bool`

`setUsePcntl(bool $usePcntl): void`

`usePcntl(): bool`

Output Configuration

`setOutput(ShellOutput $output): void`

`getOutput(): ShellOutput`

`setRawOutput(bool $rawOutput): void`

`rawOutput(): bool`

`setPager($pager): void`

`getPager(): string|OutputPager|false`

Color and Theme Configuration

`setColorMode(string $colorMode): void`

`colorMode(): string`

`setTheme($theme): void`

`theme(): Theme`

Interactive Mode

`setInteractiveMode(string $interactiveMode): void`

`interactiveMode(): string`

`getInputInteractive(): bool`

Verbosity

`setVerbosity(string $verbosity): void`

`verbosity(): string`

`getOutputVerbosity(): int`

Code Execution Configuration

`setRequireSemicolons(bool $requireSemicolons): void`

`requireSemicolons(): bool`

`setStrictTypes(bool $strictTypes): void`

`strictTypes(): bool`

`setYolo(bool $yolo): void`

`yolo(): bool`

`setCodeCleaner(CodeCleaner $cleaner): void`

`getCodeCleaner(): CodeCleaner`

Error Handling

`setErrorLoggingLevel(int $errorLoggingLevel): void`

`errorLoggingLevel(): int`

Unicode

`setUseUnicode(bool $useUnicode): void`

`useUnicode(): bool`

Tab Completion

`setUseTabCompletion(bool $useTabCompletion): void`

`useTabCompletion(): bool`

`setAutoCompleter(AutoCompleter $autoCompleter): void`

`getAutoCompleter(): AutoCompleter`