phpEnv如何开启readline扩展 phpEnv命令行输入优化

phpEnv 默认不启用 readline 扩展——这个坑不少人在多版本管理时踩过。即便你用 phpEnv 切换 PHP 版本，readline 也得单独编译进实例里，否则像 readline_list_history()、readline_write_history() 这些函数，要么直接报错，要么悄无声息地返回空数组。

phpEnv 编译时必须加 --with-readline

phpEnv 本身没有那种“点一下开启扩展”的开关，它本质上只是封装了 PHP 源码编译。要让 readline 完整可用——历史列表、补全、持久化一个不落——不能靠默认参数，关键在于编译时有没有带上 --with-readline。

• 先装系统依赖：Ubuntu/Debian 就 sudo apt install libreadline-dev，CentOS/RHEL 用 sudo yum install readline-devel。
• 安装 PHP 时显式指定参数：PHP_CONFIGURE_OPTS="--with-readline" phpenv install 8.3.5。
• 如果 PHP 已经装好，没法热启——只能重来一遍：phpenv uninstall 8.3.5 && PHP_CONFIGURE_OPTS="--with-readline" phpenv install 8.3.5。
• 漏掉 --with-readline 会怎样？readline() 函数也许还能用，但底层实际走的是 libedit。这时候 readline_list_history() 永远返回空数组，方向键、Ctrl-R 搜索这些功能全失灵。

readline_add_history() 必须手动调用

很多人以为输入完信息，历史就自动存了——其实 PHP 的 readline 没那么智能，它不像 Bash 那样默认记录。每次有效输入，都得自己显式塞进历史栈。

• 光写 $line = readline("prompt> "); 不够，后面必须跟上 if ($line !== false && trim($line) !== '') { readline_add_history($line); }。
• 注意，readline_add_history() 只影响内存里的历史，脚本一关就全丢了。要持久化，还得配上 readline_read_history() 和 readline_write_history()。
• 千万别重复调 readline_add_history("")，那会往历史里塞空行。建议先用 trim() 判断一下，再决定要不要添加。

历史文件读写：路径和权限是常见雷区

用 readline_read_history() 或 readline_write_history() 时，路径写错或目录不可写是静默失败的头号原因——完全不报错，但就是没效果。

• 路径推荐用绝对路径：$histFile = __DIR__ . '/.cli_history';。CLI 工作目录一换，相对路径就容易写错地方。
• 首次运行前，检查一下目录是否可写：if (!is_writable(dirname($histFile))) { die("历史目录不可写\n"); }。
• readline_read_history() 碰到不存在的文件不会报错，也不加载任何内容；readline_write_history() 写入失败时也不给任何 warning。得自己用 file_exists() 和 filesize() 验证一下是否真写进去了。
• 历史文件就是纯文本，每行一条命令，直接用 cat 就能看，调试起来很方便。

Tab 补全需要注册 readline_completion_function()

没注册补全回调的话，按下 Tab 键就是个普通字符，什么都不会发生。

• 回调函数必须返回数组，哪怕空数组也行：readline_completion_function(fn($input) => []);。不这么做，Tab 键甚至会卡住。
• 输入为空时（$input === ''），通常应该返回全部候选词。否则第一次按 Tab 没反应，用户会以为功能坏了。
• 补全逻辑里别用 echo 或 var_dump，会污染补全界面。想调试，建议写日志到临时文件。
• 一个实用技巧：前缀匹配用 str_starts_with($keyword, $input) 比 strpos() 更安全，能避免误匹配子串。

最后提一个最容易被忽视的点：很多人试完 readline() 能读输入就以为大功告成，但真正让 CLI 变得“像 Bash”的那些函数——readline_list_history()、readline_write_history()、readline_completion_function()——全部依赖编译时的 --with-readline。缺了它，所有高级功能都是摆设。