现代PHP开发者必备的交互式REPL与调试神器

概述

PsySH 是由 Justin Hileman 开发并维护的一个 PHP 运行时开发者控制台、交互式调试器和 REPL（Read-Eval-Print Loop）。它是 Laravel Tinker 的底层引擎，也可以独立用于任何 PHP 项目。

核心功能

• 交互式 REPL：一行一行执行 PHP 代码，自动补全（tab）、历史记录、语法高亮。
• 内置调试器：dump()、dd()、debug()、var_dump() 等命令，智能格式化输出（支持 Symfony VarDumper）。
• 异常处理：自动格式化堆栈跟踪（TraceFormatter），支持过滤、颜色化。
• 代码清理：防止常见 PHP 错误（如 return 在非函数中使用、eval 不安全、闭包问题等）。
• Shell 集成：支持 psysh 作为终端命令行工具，集成到 bash/zsh 等（Shell Integration）。
• 魔法变量：_（上次输出）、_e（异常）、
• 历史管理：持久化保存输入历史，支持多会话。
• 扩展性：大量内置命令（help、ls、var、whereami、dmesg 等），支持自定义命令、Tab 补全、主题、Pager。

主要结构

psysh/
├── bin/               # psysh 启动脚本（支持本地自动加载、项目信任机制）
├── src/               # 核心代码（Psy 命名空间）
│   ├── CodeCleaner/   # 代码安全清理器（解析、AST 转换、防止注入）
│   ├── Shell/         # 主 Shell 类（Symfony Console 扩展）
│   ├── Input/         # 输入处理（ShellInput 等）
│   ├── Output/        # 输出格式化（ShellOutput、Pager）
│   ├── Formatter/     # 堆栈格式化（TraceFormatter）
│   ├── Completion/    # Tab 补全引擎
│   ├── TabCompletion/ # 自动补全匹配器
│   ├── VarDumper/     # 变量转储增强（支持 Symfony VarDumper）
│   ├── Exception/     # 自定义异常
│   ├── Util/          # 工具类
│   └── ...            # 其他（如 Readline、ExecutionLoop）
├── test/              # 单元测试
├── vendor/            # Composer 依赖（可选，本地安装时使用）
└── README.md, composer.json 等

核心依赖（composer.json）：

• php: ^8.0 || ^7.4
• nikic/php-parser: ^5.0 || ^4.0（代码解析）
• symfony/console、symfony/var-dumper
• 建议：ext-pcntl（更好性能）、composer/class-map-generator（加速补全）

安装与运行

# 全局安装（推荐）
composer global require psy/psysh

# 本地项目（composer.json 推荐）
composer require --dev psy/psysh

# 启动
vendor/bin/psysh
# 或直接 psysh（如果已全局安装）

CLI 参数：

• --help：查看帮助
• --yolo：跳过大部分安全检查（危险！仅调试用）
• --trust-project / --no-trust-project：本地项目信任机制（防止恶意代码）
• --cwd=/path：指定工作目录

基本用法示例

// 启动 psysh

// 普通代码
echo "Hello, World!";
$var = 42;

// 变量输出（自动）
$var = "PsySH";
// 等价于 dump($var);

// 调试（自动格式化）
debug($obj);        // Psy\debug
dd($array);        // dump + die
var_dump($string); // 原始 var_dump

// 特殊命令
\Psy\info();       // 显示配置和版本
help;              // 内置帮助
ls;                // 列出当前 Shell 变量
whereami;          // 显示当前文件/类/函数
dmesg;             // 系统日志

内置命令（可通过 help 查看）：

• exec、eval、include、require
• namespace、use、class、function 等
• pager、theme、history 等配置相关

高级特性

• Tab 补全：类、方法、常量、函数、变量、命令等（支持自定义）
• 历史记录：使用 history 命令管理（保存到 ~/.psysh/history）
• 主题：自定义提示符、颜色（支持 clicolor 等）
• Pager：长输出自动分页（pager => true）
• 集成：Laravel Tinker、MediaWiki、Symfony 等项目已支持

配置文件

PsySH 支持 YAML/JSON 配置（可加载 psysh.yml 等）。

• 主题、提示符、历史文件路径、Pager、Tab 补全选项等。
• 内置示例：~/.config/psysh/config.php 或 ~/.psysh/config.php

开发者/扩展

• 自定义命令：继承 Psy\Command 并实现 execute。
• 自定义补全：实现 Psy\TabCompletion\Matcher。
• 自定义主题：实现 Psy\Theme 接口。
• 调试 API：Psy\debug(vars, bindTo)、Psy\shell()。

安装与开发注意事项

• PHP 要求：7.4+ / 8.0+
• 推荐安装：Composer（全局或本地）。
• 信任机制：防止在恶意项目中使用本地 PsySH（自动提示 --trust-project）。
• Windows 支持：良好，但 readline 依赖 Windows 10+ Build 10586+。
• 构建：make 脚本、Phan 静态分析、PHPUnit 测试。