Pheanstalk v5 版本升级指南与重大变更解析

版本升级背景

Pheanstalk 作为 PHP 的 Beanstalkd 客户端库，在 v5 版本中进行了多项架构改进和功能增强。本次升级引入了更严格的类型系统，并对 API 设计进行了现代化改造，这些变化虽然提升了代码质量和开发体验，但也带来了一些不兼容的修改。

核心变更点

1. 方法链式调用调整

v4 版本中常见的链式调用模式在 v5 中已被移除：

// v4 写法（已废弃）
$pheanstalk->watch('tube')->ignore('default')->reserve();

// v5 正确写法
$pheanstalk->watchOnly(new TubeName('tube'));
$job = $pheanstalk->reserve();

2. Tube 名称的类型安全强化

v5 版本引入了专门的 TubeName 值对象来替代字符串：

// v4 写法（已废弃）
$pheanstalk->useTube('email');

// v5 正确写法
use Pheanstalk\Values\TubeName;
$pheanstalk->useTube(new TubeName('email'));

3. 常量位置重构

多个默认值常量被重新组织到更符合逻辑的接口中：

• DEFAULT_PORT 迁移至 SocketFactoryInterface
• DEFAULT_DELAY、DEFAULT_PRIORITY 和 DEFAULT_TTR 迁移至 PheanstalkPublisherInterface

4. 方法参数命名规范化

put 方法的参数名称从简写改为更具描述性的形式：

// v4 参数名（已废弃）
$pheanstalk->put($data, $priority, $delay, $ttr);

// v5 参数名
$pheanstalk->put($data, $priority, $delay, $timeToRelease);

升级建议路径

1. 静态分析先行：使用 PHPStan 等工具进行代码扫描，快速定位类型不匹配问题
2. 逐步替换：按照变更点分类逐个修正，建议顺序：
   • 先处理 TubeName 对象转换
   • 再调整方法链式调用
   • 最后修正常量引用
3. 测试验证：特别注意任务队列的持久化和超时处理逻辑

架构设计理念

v5 版本的改动体现了以下设计原则：

1. 显式优于隐式：通过 TubeName 对象使 tube 操作更明确
2. 单一职责：将常量按功能域重新分配
3. 开发者体验：参数名更具描述性，降低理解成本
4. 类型安全：强化类型约束，减少运行时错误

对于复杂项目，建议建立过渡层逐步适配这些变更，确保系统稳定性不受影响。