GrumPHP 从 v1 升级到 v2 的技术指南

GrumPHP 从 v1 升级到 v2 的技术指南

grumphp A PHP code-quality tool 项目地址: https://gitcode.com/gh_mirrors/gr/grumphp

前言

GrumPHP 是一个优秀的 PHP 代码质量检查工具，它通过 Git 钩子自动运行代码检查任务。随着 v2 版本的发布，GrumPHP 进行了两项重大架构调整，主要影响任务和扩展的开发者。本文将详细解析这些变化，帮助开发者顺利完成升级。

升级影响范围

首先需要明确的是：

• 普通用户：v1 到 v2 的升级过程是平滑的，不会影响现有配置和使用
• 任务/扩展开发者：需要按照新规范调整代码，特别是使用了自定义任务或扩展的情况

核心架构变化

1. AMPHP v3 的引入

GrumPHP v2 采用了 AMPHP v3 作为底层异步处理框架，带来了：

• 基于 Fiber 的并行任务执行系统
• 更稳定的异步处理能力
• 完全重写的内部 API

这项变化主要影响 GrumPHP 内部架构，对大多数用户透明。

2. PHAR 分发改进

针对 grumphp-shim PHAR 分发版本的问题，v2 进行了重要调整：

• 移除了 TaskInterface 中的外部依赖
• 重构了 ExtensionInterface 以避免外部依赖
• 使扩展能够兼容 PHAR 分发版本

任务接口(TaskInterface)变更详解

新接口结构

namespace GrumPHP\Task;

use GrumPHP\Runner\TaskResultInterface;
use GrumPHP\Task\Config\ConfigOptionsResolver;
use GrumPHP\Task\Config\TaskConfigInterface;
use GrumPHP\Task\Context\ContextInterface;

interface TaskInterface
{
    public static function getConfigurableOptions(): ConfigOptionsResolver;
    public function canRunInContext(ContextInterface $context): bool;
    public function run(ContextInterface $context): TaskResultInterface;
    public function getConfig(): TaskConfigInterface;
    public function withConfig(TaskConfigInterface $config): TaskInterface;
}

关键变化

1. 移除了 Symfony OptionsResolver 的直接依赖

   • 现在使用 GrumPHP 自带的 ConfigOptionsResolver
   • 提高了与 PHAR 分发版本的兼容性

2. 配置解析器适配方法

public static function getConfigurableOptions(): ConfigOptionsResolver
{
    $resolver = new OptionsResolver();
    // 原有配置逻辑...
    return ConfigOptionsResolver::fromClosure(
        static fn (array $options): array => $resolver->resolve($options)
    );
}

重要注意事项

• 避免使用 ConfigOptionsResolver::fromOptionsResolver()
  • 在 PHAR 分发版本中，Symfony 的 OptionsResolver 会被作用域隔离(前缀处理)
  • 直接使用会导致兼容性问题

扩展系统(Extension)变更详解

新扩展接口

class MyExtension implements ExtensionInterface
{
    public function imports(): iterable {
        yield '/path/to/my/config.yaml';
    }
}

关键变化

1. 服务注册方式改变

   • 从直接在 PHP 中注册服务改为通过配置文件注册
   • 移除了 load(ContainerBuilder $container) 方法
   • 新增 imports() 方法返回配置文件路径

2. 配置文件要求

   • 必须使用 YAML、XML 或 INI 格式
   • 不支持 PHP 格式的配置文件
   • 示例 YAML 配置：

services:
  my_service:
    class: My\Service\Class
    arguments: ['@other_service']

变更原因

• 解决 PHAR 分发版本中的作用域隔离问题
• 统一扩展的配置方式
• 提高扩展在不同分发方式下的兼容性

升级步骤指南

对于任务开发者：

1. 更新 TaskInterface 实现
2. 重构配置解析逻辑，使用新的 ConfigOptionsResolver
3. 测试在 PHAR 分发版本中的兼容性

对于扩展开发者：

1. 移除 load() 方法实现
2. 创建服务注册配置文件(YAML/XML/INI)
3. 实现 imports() 方法返回配置文件路径
4. 测试在不同分发方式下的行为

总结

GrumPHP v2 的架构改进主要集中在：

1. 更现代化的异步处理基础(AMPHP v3)
2. 更好的 PHAR 分发兼容性
3. 更清晰的扩展和任务接口设计

这些变化虽然带来了短期内的升级成本，但为长期稳定性和扩展性打下了坚实基础。按照本文指南进行调整，开发者可以充分利用 v2 版本的新特性，同时确保代码在各种分发方式下都能正常工作。

grumphp A PHP code-quality tool 项目地址: https://gitcode.com/gh_mirrors/gr/grumphp