psy/psysh

Experimental interactive readline

The pure-PHP experimental readline implementation now has its own built-in pager. Long output opens in an alternate-screen pager with keyboard and mouse scrolling, search, wrap-aware layout, and sensible scrollback behavior after exit.

This is specific to PsySH's experimental userland readline, and it's another reason to give it a try:

psysh --experimental-readline

Or enable it in config:

'useExperimentalReadline' => true,

The built-in pager is enabled automatically with experimental readline, or explicitly with 'pager' => true.

We'd love your feedback! Try it out and let us know what works, what doesn't, and what still feels weird.

Better docs

doc understands more PHP manual targets directly, including structured manual page IDs like language.types.array, language type/operator pages, and language constructs like array and list. Addresses #937 (thanks @Tomirad!)

Manual output also got a big upgrade: variadic signatures make more sense; structured text, tables, and code blocks now render properly; PHP snippets get syntax highlighting; and wrapping works better across styled and wide-character output.

History improvements

• Added history --session to show, save, or replay only commands from the current REPL session
• history --clear now rejects filters and range options instead of accepting combinations it ignores

Bug fixes

• Fix exception formatting over-matching and eating the beginning of error messages. Fixes #943 (thanks @bilboque!)
• Fix timeit median calculation
• Fix sudo instantiation for classes without constructors
• Avoid deprecated reflection calls on PHP 8.4+

Under the hood

• Readline rendering now uses widgets and a shared mode stack for completion, history search, and the pager
• Release automation now creates draft releases with gh
• Removed Codecov from CI
• Added Dependabot cooldowns and updated CI dependencies. Thanks @dependabot!
• Fixed Laravel and MediaWiki smoke tests

Bug fixes

• Fix interactive readline bracket matching inside interpolated strings. Fixes #930
• Avoid infinite recursion in ShellOutput write tracking (e.g. print_r on an Exception with zend.exception_ignore_args = Off). Fixes #934
• Include --warm-autoload in project trust restrictions
• Exclude Symfony Console DI components from the autoload warmer (they're an optional dependency and blow up when not installed)

Under the hood

• Tighter callable types throughout
• Added MediaWiki downstream smoke tests, updated to 8.3
• Fixed Drush downstream tests

Runtime config and clipboard support

PsySH has a new config command for inspecting and updating runtime-configurable settings during the current session. You can tweak things like pager, theme, verbosity, useSuggestions, useSyntaxHighlighting, clipboardCommand, and semicolonsSuppressReturn without restarting the shell. Fixes #361

There’s also a new copy command for copying the last result ($_) or any expression to your clipboard. Works with system clipboard commands, or via OSC 52 for SSH and remote terminals.

Configure with clipboardCommand or useOsc52Clipboard in your config.

Semicolon-based return suppression

Optionally suppress return values by ending a statement with ;, similar to MATLAB/Octave behavior. Supports a 'double' mode requiring ;; for suppression (if requireSemicolons is also enabled, both true and 'double' require ;;).

'semicolonsSuppressReturn' => true,
'semicolonsSuppressReturn' => 'double', // Always require ;; to suppress

Output and exception display improvements

Strings are now valid PHP!

• PsySH now preserves backslashes and other characters it previously mangled in a few cases. Fixes #351, #568
• Multiline strings are rendered using heredoc-style output rather than triple-quoted strings """. The old format is available via useDeprecatedMultilineStrings until the next major release.

Providing an exceptionDetails callback via config renders additional context about exceptions (e.g. validation errors) alongside the error message. Fixes #648

A few other improvements:

• More consistent compact (and non-compact) output spacing.
• Responsive help layout adapts to terminal width.

Better completion for everyone

Legacy readline now shares PsySH’s newer completion engine, which brings much better parity between ext-readline/libedit and experimental interactive readline. Command argument completion, better multiline buffering, and a handful of command-dispatch edge cases now work much more consistently outside experimental readline too.

Commands can now define their own argument completions via CommandArgumentCompletionAware.

Interactive readline polish

New in the experimental interactive readline:

• Live syntax highlighting — code is highlighted as you type. Can be disabled via useSyntaxHighlighting if you don't like colors, I guess.
• Allman-style indenting — opening brackets on a new line get proper indentation.
• Improved auto-dedent — closing brackets automatically reduce indentation.

psy\info() and --info also report more detail about readline and autocomplete state.

Run psysh with --experimental-readline and try it out. It's getting kind of awesome!

Compatibility note

Bare config and copy at the prompt now resolve to PsySH commands before PHP function calls. Prefix ambiguous input with ; to force PHP execution.

Bug fixes

• Use aliases are now tracked by import type (class vs function vs constant), fixing resolution bugs with use function and use const statements.
• Fix pager pipe warnings when user quits pager early
• Fix eval error messages incorrectly suppressing PsySH file paths
• Improve terminal width check on oldest supported Symfony versions
• Fix a code cleaner bug with throw new Exception in PHP 7.4

Improvements

• Added --pager / --no-pager CLI options
• Richer psy\info() / --info output with interactive completion
• Added hermetic test bootstrap, PTY smoketests, and additional downstream/composer-repl coverage
• Ctrl-C now interrupts the edit command instead of waiting for the editor to close

Added an experimental interactive readline: a from-scratch pure-PHP readline replacement built specifically for PsySH. Instead of delegating to ext-readline or ext-libedit, this gives PsySH full control over input, editing, completion, and rendering.

This is opt-in and experimental. Default behavior is completely unchanged. Enable it in your config or from the command line:

'useExperimentalReadline' => true,

psysh --experimental-readline

See the interactive readline wiki page for more!

Completions that actually understand your code

The new completion engine is syntax-aware, type-aware, and runtime-value-aware. It parses your input, resolves types from live objects in scope, and completes based on what your code actually is, not just string matching on symbol names.

Type $user-> and see that object's actual methods and properties. Chain through $repo->find(1)-> and get completions for the return type. Fuzzy matching means asum finds array_sum and stl finds strtolower. Completions show in a navigable multi-column menu.

Multi-line editing

Press Enter on an incomplete statement and the input continues on the next line with proper indentation. Closing brackets auto-dedent. Shift+Enter always inserts a newline. No more fighting the shell to write a multi-line closure.

History

• Reverse history search (Ctrl+R) with an overlay showing match highlighting, smart-case filtering, deduplication, and keyboard navigation.
• Filtered history navigation: type part of a previous command, then press Up/Down to cycle through matching history entries.

And more

• Fish-style inline autosuggestions from your history. This one's still a bit rough; enable it separately with 'useSuggestions' => true.
• Bracket and quote auto-pairing with smart backspace.
• Bracketed paste mode: pastes multi-line code verbatim without executing line-by-line.
• No ext-readline or ext-libedit required. Works with any terminal.
• Ctrl+L to clear the screen.

This addresses a bunch of long-standing issues: #234, #254, #309, #346, #506, #561, #668, #732, #769, #869.

We'd love your feedback! Give it a try, and let us know what works and what doesn't. The goal is to make this the default. Help us get it there. 🧪

Project trust edge case fixes

Fixed several edge cases with the Restricted Mode introduced in v0.12.19 where non-interactive contexts (piped input, execute() calls, Composer proxy scripts) could incorrectly trigger trust prompts or restrict trusted functionality.

Fixes #913

Commands work better outside the shell

Decoupled commands from ShellOutput via a new ShellOutputAdapter, so commands degrade gracefully when used in non-interactive contexts rather than failing on missing shell features.

Improvements

• Added downstream compatibility tests for local and CI workflows
• Moved internal helper scripts from bin/ to scripts/

⚠️ Security fix

Fixed a CWD configuration poisoning vulnerability (CVE-2026-25129) where a malicious .psysh.php file in an attacker-writable directory could execute arbitrary code when a victim runs PsySH from that directory. This affects all versions prior to v0.12.19 and v0.11.23, including downstream consumers like Laravel Tinker, when invoked from an attacker-writable CWD.

Fixed in v0.12.19 and v0.11.23. Upgrade ASAP.

Restricted Mode

PsySH now requires explicit trust before loading project-local config (.psysh.php), local PsySH binaries, or Composer autoloads from untrusted projects. Trust decisions are persisted per-project in trusted_projects.json.

Configure with trustProject:

'trustProject' => 'prompt',  // default — ask interactively
'trustProject' => 'always',  // trust all projects
'trustProject' => 'never',   // always run restricted

Or use --trust-project / --no-trust-project CLI flags, or the PSYSH_TRUST_PROJECT env var.

Non-interactive sessions automatically skip untrusted features with a warning.

Magic method and property support 🪄

Tab completion, ls, doc, and show commands now recognize @method and @property docblock tags. Magic members display in magenta so you can tell them apart from real methods and properties.

Inheritance works as expected — magic members from parent classes, interfaces, and traits are included, with child declarations taking precedence.

Also fixes parsing of generic types (e.g., array<int, string>) in docblock tags, which previously broke on whitespace inside angle brackets.

See #905

Improvements

• Excluded a few unnecessary files and folders from release source zips (Thanks @reedy!)
• Fixed --cwd to actually change the working directory. Previously it only affected discovery for autoload/config, so relative paths and other directory-dependent behavior didn’t work as expected inside the shell.
• Significantly improved memory usage with older php-parser versions (pre-v4.18.0)

• Fix exit() not working when uopz extension is loaded
• Don't reopen pager if user closes it early
• Ensure stty state is restored before exiting PsySH (fixes an issue where Ctrl-C might be incorrectly handled after exiting)

Hot code reloading!!?!?1?

Install the uopz extension (5.0+) and PsySH will automatically reload modified files during your session. Edit code, switch back to PsySH, and your changes are live—no restart needed!

What gets reloaded

• Method bodies (including private/protected)
• Function implementations (and new functions!)
• Class and global constants

What can't be reloaded

• New class methods
• Class properties, inheritance, or interfaces
• Method signatures

PsySH skips "risky" reloads by default (conditional definitions, static variables). Use the new yolo command to bypass safety checks:

>>> my_helper()
Warning: Skipped conditional: if (...) { function my_helper() ... }

>>> yolo !!
=> "result"

See the documentation for more details.

Bug fixes

• Fix "array offset on null" warning on Ctrl-C — plays nicer with Laravel + PHP 8.5
• Work around O(n²) performance in Symfony OutputFormatter

A quick release adding support for Symfony Console v7.4+ and v8.x.

• Fixed CWD configuration poisoning vulnerability (CVE-2026-25129). Backported Restricted Mode from v0.12. PsySH now requires explicit trust before loading local config (.psysh.php), local PsySH binaries, or Composer autoloads from untrusted projects. Configure with trustProject config option, --trust-project / --no-trust-project CLI flags, or PSYSH_TRUST_PROJECT env var.