palantirnet/drupal8-rector

此包已 弃用 并不再维护。作者建议使用 palantirnet/drupal-rector 包代替。

使用 Rector 为您的 Drupal 代码提供即时修复。

0.20.3 2024-06-10 19:18 UTC

This package is auto-updated.

Last update: 2024-08-23 15:03:58 UTC


README

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

状态

Packagist Version Functional test: Rector examples Unit tests PHPStan

发行说明

  • 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 配置。它应该位于文档根目录旁边,例如 webdocroot

本项目使用 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.phprector_examples_updated/drupal_url.php

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

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

示例

DrupalUrlRector -> rector_examples/src/DrupalUrlStatic.phprector_examples_updated/src/DrupalUrlStatic.php

创建/更新配置文件

/config/drupal-8中的配置文件根据Drupal的次要版本进行了划分。

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

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

更新索引文件

索引文件部分用于向https://dev.acquia.com/drupal9/deprecation_status/errors提供自动化更新,这是一个跟踪覆盖情况的有用方式。PHPStan的消息也列在这里以及Drupal代码库中的变更记录注释中。

锁定开发依赖项

如果有与Rector冲突,可以在rector/rectorphpstan/phpstan上使用conflict来锁定软件包版本。

致谢

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