README

自动修复已弃用的Drupal代码。

状态

发行说明

• drupal-rector的0.18.0及以上版本将包含Rector 0.18+。升级路径应该与重新复制配置文件一样简单。cp vendor/palantirnet/drupal-rector/rector.php。

• drupal-rector的0.13.0及以上版本将包含Rector 0.13.8+。升级路径应该与重新复制配置文件一样简单。cp vendor/palantirnet/drupal-rector/rector.php

请注意，GitHub不允许我们有不同的默认主页和合并分支。如果您使用packagist/composer检查了项目，请阅读您版本的文档。

介绍

您可以在以下博客文章中了解更多详情

https://www.palantir.net/blog/jumpstart-your-drupal-9-upgrade-drupal-rector

文档

开发指南、单个弃用概述和其他资源可以在此处找到

https://www.palantir.net/rector

所有规则的列表及其示例

在docs/rules_overview.md中的规则概述

范围和限制

此工具的开发优先考虑了弃用和更新的感知影响。有许多弃用通常涉及多个组件，并且对于这些组件中的每一个，都有几种处理弃用的方法。

我们已尝试根据以下内容确定影响

• 在Drupal.org上贡献模块中弃用功能的用途
• 如果存在简单的修复弃用的方法

因此，高影响（代码在新版Drupal中为大量用户工作），低努力（我们可以根据对Rector的了解开发规则）。

常见限制

已知限制列在每个规则的注释文档中。

常见限制包括

• 使用静态调用，如Drupal->service('my_service')->myMethod();，而不是将服务注入到类中
• 跳过复杂的使用案例，例如当可选参数作为变量传递时
• 以奇怪的方式处理use语句。Rector有一个全局选项来处理use语句，我们认为其好处超过了缺点，如奇怪的位置或处理不常见模式的不足。
• 以奇怪的方式处理文档注释，尤其是在空白处。Rector使用依赖关系，有时会删除空注释或删除空白。到目前为止，Drupal Rector不打算修改任何文档注释，但Rector最终会这样做。

我们希望随着我们对Rector了解的加深，我们可能能够更新这些规则以添加这些功能。

问题在drupal.org上管理

https://www.drupal.org/project/issues/rector

有关贡献建议，请参阅本文档的后面部分。

安装

注意：要获得最佳体验，您的Drupal站点应运行版本8.9或更高。

在Drupal项目中安装Drupal Rector。

$ composer require --dev palantirnet/drupal-rector

在您的项目中创建一个配置文件

您需要在存储库的根目录中有一个rector.php配置。它应该位于您的文档根目录旁边，例如web或docroot。

本项目使用 webflo/drupal-finder 来查找包含 Drupal 的文档根目录。

要开始使用，请复制本包提供的 rector.php 配置文件。

cp vendor/palantirnet/drupal-rector/rector.php .

默认情况下，Drupal Rector 将修复所有版本 Drupal 中的已弃用代码。如果您想更改此行为，请修改 rector.php 配置中使用的集合。例如，如果您的站点仍在 Drupal 9.3 上，并且您无法修复 Drupal 9.4 中创建的弃用代码，请使用以下配置：

$rectorConfig->sets([
    Drupal9SetList::DRUPAL_90,
    Drupal9SetList::DRUPAL_91,
    Drupal9SetList::DRUPAL_92,
    Drupal9SetList::DRUPAL_93,
]);

这比 Drupal9SetList::DRUPAL_9 集合更细粒度。

建议的工作流程

1. 使用 Rector 分析您的代码并审查建议的更改

$ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run

1. 应用建议的更改

$ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]

有关 Rector 的更多信息，请参阅此处。

故障排除

PhpStan composer 问题

在安装此包之前，您可能需要使用 Composer 升级 phpstan/phpstan。

Rector 与较旧版本的 PhpStan 存在冲突。

无法找到 Rector 规则类

如果您遇到以下错误

[ERROR] 在加载时未找到类 "DrupalRector\Drupal8\Rector\Deprecation\EntityManagerRector"

您可能需要重建您的自动加载文件。

composer dump-autoload

FileLocator::locate() 必须与 FileLocatorInterface::locate() 兼容

如果您遇到以下错误

PHP Fatal error:  Declaration of _HumbugBox3630ef99eac4\Symfony\Component\HttpKernel\Config\FileLocator::locate($file, $currentPath = NULL, $first = true) must be compatible with _HumbugBox3630ef99eac4\Symfony\Component\Config\FileLocatorInterface::locate(string $name, ?string $currentPath = NULL, bool $first = true) in phar:///var/www/html/vendor/rector/rector-prefixed/rector/vendor/symfony/http-kernel/Config/FileLocator.php on line 20
Fatal error: Declaration of _HumbugBox3630ef99eac4\Symfony\Component\HttpKernel\Config\FileLocator::locate($file, $currentPath = NULL, $first = true) must be compatible with _HumbugBox3630ef99eac4\Symfony\Component\Config\FileLocatorInterface::locate(string $name, ?string $currentPath = NULL, bool $first = true) in phar:///var/www/html/vendor/rector/rector-prefixed/rector/vendor/symfony/http-kernel/Config/FileLocator.php on line 20

您可能需要检查您是否在

• 从支持 Php 7.2 或更高版本的环境运行 composer install
• 从支持 Php 7.2 或更高版本的环境运行 Drupal Rector

有时，人们从一台机器（宿主机器）安装 composer 依赖项，并在另一台机器（例如 Lando VM）上运行 Drupal Rector。

如果您遇到这些问题，请尝试从具有 Php 7.2 或更高版本的环境运行 Rector。Drupal Rector 不需要一个完全功能的 Web 服务器，它只需要（更多或更少）Php 和访问标准 Drupal 文件集。

在 Alpine Docker 中运行 Rector 时出现 Iconv 错误

如果您遇到以下错误

iconv(): 错误的字符集，从 UTF-8 到 ASCII//TRANSLIT//IGNORE 的转换不允许

您可以在 Dockerfile 中通过以下方式修复它：

# fix work iconv library with alphine
RUN apk add --no-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/ --allow-untrusted gnu-libiconv
ENV LD_PRELOAD /usr/lib/preloadable_libiconv.so php

感谢 @zolotov88 在 nunomaduro/phpinsights#43 (评论) 中提出

开发和贡献建议

感谢您对贡献的兴趣！

我们的目标是使人们轻松地为该项目做出贡献。虽然我们已在这里做出了一些架构决策，以期实现这一目标，但这仍是一个正在进行中的工作，我们欢迎反馈。

开发环境

请参阅 README 中的说明。

添加 Rector 规则

如果您想提交 Rector 规则，我们正在寻找以下内容

• 一个 Rector 规则类，请参阅 /src/Rector/Deprecation 以查看现有规则
• 一个示例文件或文件集，显示了前后变化，请参阅 /rector_examples 和 /rector_examples_updated
• 一个更新的配置文件，用于注册 Rector 规则，请参阅 /config/drupal-8
• 索引文件中的列表，请参阅 /deprecation-index.yml

指南

目前有一些指南可用，我们鼓励人们创建更多指南，以提供他们的观点并帮助我们更好地理解这个工具。

创建 Rector 规则的视频指南

https://www.palantir.net/rector/creating-drupal-rector-rule

其他文档和链接

https://www.palantir.net/rector

快速(?) 概述

创建 Rector 规则类

Rector 规则应按弃用名称命名，包括类名。

Drupal::url() -> DrupalUrlRector.php drupal_set_message() -> DrupalSetMessageRector.php

我们希望每个弃用都有一个Rector规则。一些弃用包括更新多个内容，这些将会有单独的规则。

为了避免重复，我们在可能的情况下为简单的重复模式创建了基类。这些以Base.php结尾，位于/src/Rector/Deprecation/Base。在这些规则中，你将扩展基类，定义类属性，添加类注释，并定义定义。

Rector支持向规则传递参数，你也可以以各种方式定义你的规则。为了避免新开发者的困惑，我们正在努力避免这些高级功能，以便熟悉有限工具的人可以轻松地确定事物所在的位置以及它们在做什么。如果复制粘贴挑战不值得这个权衡，我们可以随着进展重新评估。欢迎提出建议。

创建示例

我们正在创建成对的示例文件。

这些应该与弃用的名称相同。所以，DrupalUrlRector有一个rector_examples/drupal_url.php示例。还应创建一个rector_examples_updated/drupal_url.php示例来显示更新的代码。你可以运行Drupal Rector在这个文件上以显示更新。

示例

DrupalUrlRector -> rector_examples/drupal_url.php 和 rector_examples_updated/drupal_url.php

如果你想在类中展示代码的使用，你可以将类添加到/rector_examples/src或/rector_examples/test目录的适当位置。示例模块中的大多数示例都是services，因为它们是独立的类。

由于这些类可以使用静态调用、依赖注入或特性来访问服务、常量等，我们在一些类名中添加了更多详细信息。例如，使用*Static来表示类没有使用依赖注入。

示例

DrupalUrlRector -> rector_examples/src/DrupalUrlStatic.php 和 rector_examples_updated/src/DrupalUrlStatic.php

创建/更新配置文件

/config/drupal-8中的配置文件按Drupal的次版本号拆分。

将你的Rector规则添加到相关文件。

键是Rector规则的完全限定类名。键是yaml空值~。

更新索引文件

索引文件部分用于提供https://dev.acquia.com/drupal9/deprecation_status/errors的自动化更新，这是一个跟踪覆盖率的很有帮助的方法。该页面上还列出了PHPStan消息，以及Drupal代码库中的更改记录注释。

锁定dev依赖项

如果有与Rector冲突，可以在rector/rector和phpstan/phpstan上使用conflict锁定包版本。

• 查看GitHub上提交的树以及它的composer/installed.json文件（例如https://github.com/rectorphp/rector/blob/0.12.18/vendor/composer/installed.json）。
• 使用引用来锁定phpstan/phpstan依赖项。

致谢

当前开发由Palantir.net赞助。
最初开发由Pronovix赞助。