palantirnet / drupal8-rector
Requires
- rector/rector: ^1.0
- webflo/drupal-finder: ^1.2
Requires (Dev)
- php: ^8.2
- cweagans/composer-patches: ^1.7.2
- friendsofphp/php-cs-fixer: ^3.58
- phpstan/extension-installer: ^1.1
- phpstan/phpstan: ^1.0
- phpstan/phpstan-deprecation-rules: ^1.0
- phpunit/phpunit: ^10.0
- symfony/yaml: ^5 || ^6 || ^7
- symplify/vendor-patches: ^11.0
Replaces
- dev-main
- 0.20.3
- 0.20.2
- 0.20.1
- 0.20.0
- 0.19.2
- 0.19.1
- 0.19.0
- 0.18.6
- 0.18.5
- 0.18.4
- 0.18.3
- 0.18.2
- 0.18.1
- 0.18.0
- 0.15.1
- 0.15.0
- 0.13.1
- 0.13.0
- 0.12.4
- 0.12.3
- 0.12.2
- 0.12.1
- 0.12.0
- 0.11.4
- 0.11.3
- 0.11.2
- 0.11.1
- 0.11.0
- 0.10.0
- 0.5.6
- 0.5.5
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- 0.4.1
- 0.4.0
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.0
- dev-feature/entity-reference-trait
- dev-feature/phpunit-10-rules
- dev-hotfix/docs-workaround
- dev-feature/test-master-request
- dev-feature/annotation-rules
- dev-feature/versioned-rename-class
- dev-bugfix/bytesize-markup
- dev-task/php-8.2
- dev-bbrala-patch-4
- dev-feature/annotation-configentitytype
- dev-add-author
- dev-feature/class-const-move
- dev-fix/move-rector-to-rectornamespace
- dev-feature/external-package-levels
- dev-feature/rector-1.0
- dev-fix/double-deprecated-call-issue
- dev-fix/codestyle
- dev-feature/upgrade-rector
- dev-feature/conflict-rector-0.19
- dev-hotfix/9.3-deprecation-not-in-config
- dev-feature/rector-toInt-to-toNumber
- dev-feature/9.3-FILE_STATUS_PERMANENT
- dev-feature/module-load-include
- dev-action-attributes
- dev-bug/entitymanagerrector
- dev-wip/entity-reference-class-aslias
- dev-feature/better-workflow
- dev-feature/phpunit-setup-teardown
- dev-feature/system-time-zones-rector
- dev-bbrala-patch-3
- dev-feature/codestyle-nofix
- dev-feature/codestyle
- dev-fix/fix-tests-fqcn
- dev-feature/restructure-by-major
- dev-bbrala-patch-2
- dev-bbrala-patch-1
- dev-hotfix/add-watchdog-to-setlist
- dev-fix/missing-phpunit-drupal-9
- dev-fix/drupal-get-path
- dev-fix/url-info
- dev-feature/watchdog-exception-rector
- dev-test/multiple-fixes
- dev-fix/extentionpathrector-assign
- dev-feature/9.3-taxonomy-rectors
- dev-update-badges
- dev-feature/bc-rules
- dev-feature/bc-rules-with-configuration
- dev-feature/drupal-10
- dev-feature/rector-0.18.0
- dev-feature/method-to-method-with-check-rector
- dev-feature/function-to-static-rector
- dev-stan-fails
- dev-rector-0.10
- dev-feature/run-github-actions-using-act
- dev-docs
- dev-feature/phpunit-poc
- dev-feature/path-alias-service
- dev-legacy-drupal-check-conflict
This package is auto-updated.
Last update: 2024-08-23 15:03:58 UTC
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
集合更精细。
建议的工作流程
- 使用 Rector 分析您的代码并审查建议的更改
$ vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run
- 应用建议的更改
$ 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赞助。