Why Every Modern PHP Developer Needs PsySH: An Interactive REPL and Debugger

Overview

PsySH, created and maintained by Justin Hileman, is a PHP runtime developer console, interactive debugger, and REPL (Read‑Eval‑Print Loop). It serves as the underlying engine of Laravel Tinker and can be used independently in any PHP project.

Core Features

Interactive REPL : Executes PHP code line by line with tab auto‑completion, command history, and syntax highlighting.

Built‑in Debugger : Commands dump(), dd(), debug(), var_dump() provide smart, formatted output using Symfony VarDumper.

Exception Handling : Automatic stack‑trace formatting with TraceFormatter, supporting filtering and colorization.

Code Cleaner : Prevents common PHP errors such as using return outside functions, unsafe eval, and closure issues.

Shell Integration : psysh works as a terminal command and integrates with bash / zsh etc.

Magic Variables : $_ (last output), $_e (exception), __$psysh__ and others.

History Management : Persists input history across sessions.

Extensibility : Numerous built‑in commands ( help, ls, whereami, dmesg, …) and support for custom commands, themes, and pager.

Main Structure

psysh/
├── bin/               # psysh startup script (local autoload, project trust)
├── src/               # core code (Psy namespace)
│   ├── CodeCleaner/   # code safety, parsing, AST conversion
│   ├── Shell/         # main Shell class (extends Symfony Console)
│   ├── Input/         # input handling (ShellInput, etc.)
│   ├── Output/        # output formatting (ShellOutput, Pager)
│   ├── Formatter/     # stack trace formatting (TraceFormatter)
│   ├── Completion/    # tab‑completion engine
│   ├── TabCompletion/ # auto‑completion matcher
│   ├── VarDumper/     # variable dumping (Symfony VarDumper support)
│   ├── Exception/    # custom exceptions
│   ├── Util/          # utility classes
│   └── ...            # other components (Readline, ExecutionLoop)
├── test/              # unit tests
├── vendor/            # Composer dependencies (optional)
└── README.md, composer.json etc.

Core Dependencies (composer.json)

php

: ^8.0 || ^7.4 nikic/php-parser: ^5.0 || ^4.0 (code parsing) symfony/console, symfony/var-dumper Recommended optional extensions: ext-pcntl (better performance), composer/class-map-generator (faster completion)

Installation & Running

# Global installation (recommended)
composer global require psy/psysh

# Local project (add to composer.json)
composer require --dev psy/psysh

# Start the REPL
vendor/bin/psysh
# Or simply `psysh` if installed globally

CLI Options

--help

: Show help --yolo: Skip most safety checks (dangerous, for debugging only) --trust-project / --no-trust-project: Project trust mechanism to prevent malicious code execution --cwd=/path: Specify working directory

Basic Usage Example

// Start psysh

// Normal PHP code
echo "Hello, World!";
$var = 42;

// Variable output (automatic)
$var = "PsySH"; // equivalent to dump($var);

// Debugging (auto‑formatted)
debug($obj);      // Psy\debug
dd($array);        // dump + die
var_dump($string); // original var_dump

// Special commands
\Psy\info();      // show config and version
help;              // built‑in help
ls;                // list current Shell variables
whereami;          // show current file/class/function
dmesg;             // system log

Built‑in Commands

Use help to view the full list. Notable commands include: exec, eval, include,

require

namespace

, use, class,

function

pager

, theme, history (configuration related)

Advanced Features

Tab Completion : Classes, methods, constants, functions, variables, commands (customizable).

History : Managed via history command, saved to ~/.psysh/history.

Themes : Custom prompts and colors, supports clicolor and similar.

Pager : Automatic paging for long output ( pager => true).

Integration : Already supported in Laravel Tinker, MediaWiki, Symfony, etc.

Configuration File

PsySH can load YAML or JSON configuration files such as psysh.yml. Configurable items include theme, prompt, history file path, pager, tab‑completion options, and more. Example locations are ~/.config/psysh/config.php or ~/.psysh/config.php.

Developer / Extension

Custom commands: extend Psy\Command and implement execute.

Custom completion: implement Psy\TabCompletion\Matcher.

Custom themes: implement Psy\Theme interface.

Debug API: Psy\debug($vars, $bindTo) and Psy\shell().

Installation & Development Notes

PHP requirement: 7.4+ / 8.0+

Recommended installation via Composer (global or local).

Trust mechanism: prevents usage in malicious projects (use --trust-project).

Windows support: works well, but requires readline on Windows 10+ Build 10586+.

Build tools: make scripts, Phan static analysis, PHPUnit tests.