Configuration Options

All configuration options available in PsySH, extracted from the source code with their actual default values.

Directories and Files

configDir

string

default:"~/.config/psysh"

Directory for configuration files

'configDir' => '/custom/config/path',

Overrides the default XDG config directory location.

dataDir

string

default:"~/.local/share/psysh"

Directory for data files (PHP manual, etc.)

'dataDir' => '/custom/data/path',

runtimeDir

string

default:"/tmp/psysh"

Directory for temporary runtime files

'runtimeDir' => '/custom/runtime/path',

historyFile

string

default:"~/.config/psysh/psysh_history"

Path to the readline history file

'historyFile' => '/path/to/custom_history',

manualDbFile

string

default:"~/.local/share/psysh/php_manual.php"

Path to the PHP manual database file

'manualDbFile' => '/path/to/php_manual.php',

Supports both v3 format (.php) and legacy v2 format (.sqlite).

History Management

historySize

int

default:"0 (unlimited)"

Maximum number of history entries to save

'historySize' => 10000,

Set to 0 for unlimited history.

eraseDuplicates

bool

default:"null (disabled)"

Remove duplicate entries from history

'eraseDuplicates' => true,

When enabled, only the most recent instance of a command is kept.

Input and Output

colorMode

string

default:"'auto'"

Control colored output

'colorMode' => 'forced',  // Always use colors
'colorMode' => 'disabled', // Never use colors
'colorMode' => 'auto',     // Auto-detect (default)

Valid values: 'auto', 'forced', 'disabled'

interactiveMode

string

default:"'auto'"

Control interactive input

'interactiveMode' => 'forced',   // Force interactive mode
'interactiveMode' => 'disabled', // Non-interactive (requires piped input)
'interactiveMode' => 'auto',     // Auto-detect (default)

Valid values: 'auto', 'forced', 'disabled'

verbosity

string

default:"'normal'"

Output verbosity level

'verbosity' => 'quiet',        // Minimal output
'verbosity' => 'normal',       // Standard output (default)
'verbosity' => 'verbose',      // Detailed output
'verbosity' => 'very_verbose', // More detailed
'verbosity' => 'debug',        // Debug information

rawOutput

bool

default:"false"

Use raw var_export style output (non-interactive mode only)

'rawOutput' => true,

Output pager command for long output

'pager' => 'more',              // Use 'more' command
'pager' => 'less -R',           // Custom less options
'pager' => false,               // Disable paging

Defaults to cli.pager ini value or auto-detects less.

Readline Configuration

useReadline

bool

default:"true (if available)"

Enable readline support for line editing

'useReadline' => false,

Automatically disabled if readline extension is not available.

useBracketedPaste

bool

default:"false"

Enable bracketed paste mode (GNU readline only)

'useBracketedPaste' => true,

When working, prevents tabs from autocompleting and newlines from executing during paste. Can be unstable.

useTabCompletion

bool

default:"true (if readline available)"

Enable tab completion

'useTabCompletion' => false,

Code Execution

usePcntl

bool

default:"true (if available)"

Enable process control (pcntl) for forking code execution

'usePcntl' => false,

Automatically disabled when XDebug debugger is active.

requireSemicolons

bool

default:"false"

Require semicolons at the end of statements

'requireSemicolons' => true,

By default, PsySH auto-inserts semicolons when missing.

strictTypes

bool

default:"false"

Enable strict type declarations

'strictTypes' => true,

Equivalent to declare(strict_types=1) in PHP.

yolo

bool

default:"false"

Run with minimal input validation

'yolo' => true, // Not recommended!

You probably don’t want this. It disables important safety checks.

errorLoggingLevel

int

default:"E_ALL"

Error reporting level for automatic logging

'errorLoggingLevel' => E_ALL & ~E_DEPRECATED,
'errorLoggingLevel' => 0, // Disable error logging

By default, PsySH logs all errors regardless of error_reporting level.

Code Cleaning and Analysis

codeCleaner

CodeCleaner

default:"(auto-created)"

Custom CodeCleaner instance for input validation

'codeCleaner' => new \Psy\CodeCleaner($parser, $traverser),

implicitUse

false|array

default:"false"

Automatically add use statements for unqualified class references

// Disable (default)
'implicitUse' => false,

// Enable for specific namespaces
'implicitUse' => [
    'includeNamespaces' => ['App\\', 'Domain\\'],
],

// With exclusions
'implicitUse' => [
    'includeNamespaces' => ['App\\'],
    'excludeNamespaces' => ['App\\Legacy\\'],
],

Works best with --warm-autoload to pre-load classes.

Display and Presentation

theme

string|array|Theme

default:"'modern'"

Output theme for colors and prompts

'theme' => 'modern',   // Modern theme (default)
'theme' => 'compact',  // Compact output
'theme' => 'classic',  // Classic >>> prompt

// Custom theme configuration
'theme' => [
    'compact' => true,
    'prompt' => '>> ',
    'styles' => [
        'error' => ['white', 'red', ['bold']],
    ],
],

See Themes documentation for details.

prompt

string

default:"null"

Custom prompt string

'prompt' => '>>> ',

Deprecated: Use theme configuration instead. This option is maintained for backward compatibility.

formatterStyles

array

default:"[]"

Custom output formatter styles

'formatterStyles' => [
    'error' => ['white', 'red', ['bold']],
    'warning' => ['black', 'yellow'],
],

Deprecated: Use theme configuration instead.

useUnicode

bool

default:"true"

Use Unicode characters in PsySH output

'useUnicode' => false,

forceArrayIndexes

bool

default:"false"

Always show array indexes in output, even for sequential arrays

'forceArrayIndexes' => true,

Startup and Messages

defaultIncludes

array

default:"[]"

Files to include automatically at startup

'defaultIncludes' => [
    __DIR__.'/bootstrap.php',
    __DIR__.'/helpers.php',
],

startupMessage

string

default:"null"

Custom message to display at startup

'startupMessage' => 'Welcome to MyApp Console!',

Project Trust and Security

trustProject

bool|string

default:"'prompt'"

Control loading of local project configurations

'trustProject' => 'always',  // Always trust project configs
'trustProject' => 'never',   // Never trust (Restricted Mode)
'trustProject' => 'prompt',  // Prompt user (default)
'trustProject' => true,      // Same as 'always'
'trustProject' => false,     // Same as 'never'

Autoload Warming

warmAutoload

bool|array

default:"false"

Pre-load classes for better tab completion

// Enable with defaults
'warmAutoload' => true,

// Disable (default)
'warmAutoload' => false,

// Custom configuration
'warmAutoload' => [
    'maxDepth' => 3,
    'maxNamespaceLength' => 50,
],

// Custom warmers
'warmAutoload' => [
    'warmers' => [
        new MyCustomAutoloadWarmer(),
    ],
],

Requires project trust for Composer autoload files.

Logging

logging

callable|LoggerInterface|array

default:"null"

Log PsySH input and execution

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

// PSR-3 logger with defaults
'logging' => $psrLogger,

// Granular control
'logging' => [
    'logger' => $psrLogger,
    'level' => [
        'input'   => 'info',    // Log user input
        'command' => false,     // Don't log commands
        'execute' => 'debug',   // Log executed code
    ],
],

Update Checking

updateCheck

string

default:"'weekly'"

How often to check for PsySH updates

'updateCheck' => 'always',  // Check every run
'updateCheck' => 'daily',   // Once per day
'updateCheck' => 'weekly',  // Once per week (default)
'updateCheck' => 'monthly', // Once per month
'updateCheck' => 'never',   // Disable update checks

updateManualCheck

string

default:"'weekly'"

How often to check for PHP manual updates

'updateManualCheck' => 'always',
'updateManualCheck' => 'daily',
'updateManualCheck' => 'weekly',  // Default
'updateManualCheck' => 'monthly',
'updateManualCheck' => 'never',

Advanced Configuration

warnOnMultipleConfigs

bool

default:"false"

Emit warnings when multiple config files are found

'warnOnMultipleConfigs' => true,

Helps identify conflicting configuration files.

Programmatic Configuration

These options are typically set via methods rather than config arrays:

Adding Custom Commands

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

Adding Tab Completion Matchers

$config->addMatchers([
    new MyCustomMatcher(),
]);

Adding Variable Casters

$config->addCasters([
    'MyApp\\User' => 'MyApp\\Casters\\UserCaster::cast',
    'MyApp\\Product' => function ($obj, $caster, $depth) {
        // Custom casting logic
        return [
            'id' => $obj->getId(),
            'name' => $obj->getName(),
        ];
    },
]);

Get Started

Usage Guide

Commands

Configuration

Advanced

Configuration Options

Directories and Files

History Management

Input and Output

Readline Configuration

Code Execution

Code Cleaning and Analysis

Display and Presentation

Startup and Messages

Project Trust and Security

Autoload Warming

Logging

Update Checking

Advanced Configuration

Programmatic Configuration

Adding Custom Commands

Adding Tab Completion Matchers

Adding Variable Casters

Build docs developers (and LLMs) love

Get Started

Usage Guide

Commands

Configuration

Advanced

​Directories and Files

​History Management

​Input and Output

​Readline Configuration

​Code Execution

​Code Cleaning and Analysis

​Display and Presentation

​Startup and Messages

​Project Trust and Security

​Autoload Warming

​Logging

​Update Checking

​Advanced Configuration

​Programmatic Configuration

​Adding Custom Commands

​Adding Tab Completion Matchers

​Adding Variable Casters

Build docs developers (and LLMs) love

Directories and Files

History Management

Input and Output

Readline Configuration

Code Execution

Code Cleaning and Analysis

Display and Presentation

Startup and Messages

Project Trust and Security

Autoload Warming

Logging

Update Checking

Advanced Configuration

Programmatic Configuration

Adding Custom Commands

Adding Tab Completion Matchers

Adding Variable Casters