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 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代码库中的变更记录注释中。

锁定开发依赖项

如果有与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赞助。