casters

PsySH uses symfony/var-dumper’s casters for presenting scalars, resources, arrays and objects. You can enable additional casters, or write your own! See caster documentation.

Default: []

codeCleaner

Provide a custom CodeCleaner instance or configuration to modify how user input is validated and transformed before execution. This is an advanced option for customizing PsySH's code transformation pipeline.

Default: Default CodeCleaner with standard passes

colorMode

By default, output contains colors if support for them is detected. To override, use \Psy\Configuration::COLOR_MODE_FORCED to force colors in output, and \Psy\Configuration::COLOR_MODE_DISABLED to disable colors in output.

Default: \Psy\Configuration::COLOR_MODE_AUTO

commands

While PsySH ships with a bunch of great commands, it's possible to add your own for even more awesome. Any Psy command added here will be available in your Psy shell sessions.

Default: []

configDir

Override the configuration directory location. By default, PsySH follows the XDG Base Directory specification (~/.config/psysh on Unix-like systems, %APPDATA%\PsySH on Windows).

Default: follows XDG specification

dataDir

Override the data directory location where PsySH stores history and other persistent data. By default, follows the XDG Base Directory specification (~/.local/share/psysh on Unix-like systems, %APPDATA%\PsySH on Windows).

Default: follows XDG specification

defaultIncludes

"Default includes" will be included once at the beginning of every PsySH session. This is a good place to add autoloaders for your favorite libraries.

Default: []

eraseDuplicates

If set to true, the history will not keep duplicate entries. Newest entries override oldest. This is the equivalent of the HISTCONTROL=erasedups setting in bash.

Default: false

errorLoggingLevel

While PsySH respects the current error_reporting level, and doesn’t throw exceptions for all errors, it does log all errors regardless of level. Set errorLoggingLevel to 0 to prevent logging non-thrown errors. Set it to any valid error_reporting value to log only errors which match that level.

Default: E_ALL

forceArrayIndexes

Always show array indexes (even for numeric arrays)

Default: false

formatterStyles (deprecated)

Override output formatting colors. These have been replaced by 🎨 Themes. To migrate existing settings change them from formatterStyles:

'formatterStyles' => [
  // name => [foreground, background, [options]],
  'error' => ['black', 'red', ['bold']],
],

… to custom theme styles:

'theme' => [
  'styles' => [
    // name => [foreground, background, [options]],
    'error' => ['black', 'red', ['bold']],
  ],
],

Default: []

historySize

Sets the maximum number of entries the history can contain. If set to zero, the history size is unlimited.

Default: 0

implicitUse

Automatically add use statements for unqualified class references. When you reference a class by its short name (e.g., User) and there's exactly one match in configured namespaces, PsySH automatically adds the use statement.

Works great with warmAutoload to make class references feel natural. The ls, doc, and show commands also benefit from implicit use statements, resolving short class names the same way your code does.

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

Default: false

interactiveMode

PsySH defaults to interactive mode in a terminal, and non-interactive mode when input is coming from a pipe. To override, use \Psy\Configuration::INTERACTIVE_MODE_FORCED to force interactive mode, \Psy\Configuration::INTERACTIVE_MODE_DISABLED to force non-interactive mode, and \Psy\Configuration::INTERACTIVE_MODE_AUTO to choose based on the type of connection (terminal or pipe).

Default: \Psy\Configuration::INTERACTIVE_MODE_AUTO

logging

Log user input, commands, and executed code to a PSR-3 compatible logger or callback. Useful for audit trails and debugging.

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

// PSR-3 logger with defaults (input=info, command=info, execute=debug)
'logging' => $psrLogger,

// Set a single log level for everything
'logging' => [
    'logger' => $psrLogger,
    'level' => 'info',
],

// Granular control per event type
'logging' => [
    'logger' => $psrLogger,
    'level' => [
        'input'   => 'info',   // User code input
        'command' => false,    // Disable command logging
        'execute' => 'debug',  // Cleaned code before execution
    ],
],

Default: false (logging disabled)

manualDbFile

Override the location of the PHP manual database file used by the doc command. By default, this is stored in the data directory.

Default: {dataDir}/php_manual.sqlite

matchers

You can write your own tab completion matchers, too! Here are some that enable tab completion for MongoDB database and collection names:

[
  new \Psy\TabCompletion\Matcher\MongoClientMatcher,
  new \Psy\TabCompletion\Matcher\MongoDatabaseMatcher,
]

Default: []

pager

If this is not set, it falls back to less. It is recommended that you set up cli.pager in your php.ini with your preferred output pager.

If you want to use a different pager only for Psy shell sessions, you can override it here.

Default: cli.pager ini setting

prompt (deprecated)

Specify a custom prompt. This has been replaced by 🎨 Themes. To migrate existing settings change this from prompt:

'prompt' => '$> ',

… to custom theme configuration:

'theme' => [
  'prompt' => '$> ',
],

rawOutput

Print var_export-style return values. This is set by the --raw-output (-r) flag, and really only makes sense when non-interactive, e.g. executing stdin.

Default: false

requireSemicolons

PsySH automatically inserts semicolons at the end of input if a statement is missing one. To disable this, set requireSemicolons to true.

Default: false

runtimeDir

Set the shell's temporary directory location. Defaults to /psysh inside the system's temp dir unless explicitly overridden.

Default: follows XDG runtimeDir specification.

startupMessage

Display an additional startup message. You can color and style the message thanks to the Symfony Console tags. See coloring docs for more details.

Default: ""

strictTypes

Enforce strict types by default. When enabled, all code executed in PsySH will run with declare(strict_types=1) behavior.

'strictTypes' => true,

Default: false

theme

PsySH supports output themes, which control prompt strings, formatter styles and colors, and compact output.

Available options are modern, compact, classic or a custom theme. See 🎨 Themes for more info.

'theme' => 'modern',

Default: "modern"

updateCheck

Frequency of update checks when starting an interactive shell session. Valid options are "always", "daily", "weekly", and "monthly".

To disable update checks entirely, set to "never".

Default: "weekly"

updateManualCheck

Frequency of PHP manual update checks. Valid options are "always", "daily", "weekly", "monthly", and "never".

'updateManualCheck' => 'monthly',

Default: "weekly"

useBracketedPaste

Enable bracketed paste support. If you use PHP built with readline (not libedit) and a relatively modern terminal, enable this.

Default: false

usePcntl

By default, PsySH will use a 'forking' execution loop if pcntl is installed. This is by far the best way to use it, but you can override the default by explicitly disabling this functionality here.

Default: true

useReadline

PsySH uses readline if you have it installed, because interactive input is pretty awful without it. But you can explicitly disable it if you hate yourself or something.

If readline is disabled (or unavailable) then terminal input is subject to the line discipline provided for TTYs by the OS, which may impose a maximum line size (4096 chars in GNU/Linux, for example) with larger lines being truncated before reaching PsySH.

Default: true

useTabCompletion

You can disable tab completion if you want to. Not sure why you’d want to.

Default: true

useUnicode

PsySH uses a couple of UTF-8 characters in its own output. These can be disabled, mostly to work around code page issues. Because Windows.

Note that this does not disable Unicode output in general, it just makes it so PsySH won’t output any itself.

Default: true

verbosity

Change output verbosity. This is equivalent to the --verbose, -vv, -vvv and --quiet command line flags. Choose from:

• \Psy\Configuration::VERBOSITY_QUIET (this is really quiet)
• \Psy\Configuration::VERBOSITY_NORMAL
• \Psy\Configuration::VERBOSITY_VERBOSE
• \Psy\Configuration::VERBOSITY_VERY_VERBOSE
• \Psy\Configuration::VERBOSITY_DEBUG

Default: \Psy\Configuration::VERBOSITY_NORMAL

warmAutoload

Enable autoload warming to improve command support and tab completion. When enabled PsySH will pre-load classes at startup, making them available to tab completion and the namespace-aware ls, doc and show commands.

This is equivalent to the --warm-autoload command line flag.

Enable with defaults (autoload projects classes only, and skip tests):

'warmAutoload' => true,

Advanced configuration:

'warmAutoload' => [
    // Include vendor packages
    'includeVendor' => true,

    // Include test classes
    'includeTests' => true,

    // Include only specific namespaces
    'includeNamespaces' => ['App\\', 'Lib\\'],

    // Exclude specific namespaces
    'excludeNamespaces' => ['App\\Legacy\\'],

    // Include specific vendor namespaces
    'includeVendorNamespaces' => ['Symfony\\Component\\', 'Doctrine\\'],

    // Exclude specific namespaces
    'excludeVendorNamespaces' => ['Symfony\\VarDumper\\'],

    // Provide custom warmers
    'warmers' => [new MyCustomWarmer()],
],

Default: false

warnOnMultipleConfigs

If multiple versions of the same configuration or data file exist, PsySH will use the file with highest precedence, and will silently ignore all others. With this enabled, a warning will be emitted (but not an exception thrown) if multiple configuration or data files are found.

This will default to true in a future release, but is false for now.

Default: false

yolo

Run PsySH without input validation. You don't want this.

Default: false