phpstan-todo-by: 带有到期日的注释
PHPStan扩展,用于检查带有到期日的TODO/FIXME/XXX
注释。
灵感来自parker-codes/todo-by。
示例
主要思想是,当满足某个条件时(例如达到某个日期、符合某个版本、某个问题追踪票据关闭),源代码中的注释将转化为PHPStan错误。
<?php
// TODO: 2023-12-14 这条注释将在2023年12月14日变成PHPStan错误
function doFoo() { /* ... */ }
// TODO https://github.com/staabm/phpstan-todo-by/issues/91 当这个GitHub问题关闭时修复我
class FooClass {}
// TODO: <1.0.0 这必须在此仓库的第一个主要版本中完成
function doBar() { /* ... */ }
// FIXME: phpunit/phpunit:5.3 当更新phpunit到5.3.x或更高版本时必须修复这个
function doFooBar() { /* ... */ }
// XXX: php:8 当需要php 8.x时删除这个polyfill
// TODO: APP-2137 当问题追踪票据解决时这个注释会报错
function doBaz() { /* ... */ }
支持的todo格式
todo注释也可以只包含一个约束条件而没有任何文本,如// @todo 2023-12-14
。
如果在日期后给出文本,这个文本将被用作PHPStan错误消息。
todo
、TODO
、tOdO
、FIXME
、XXX
关键词不区分大小写todo
关键词可以前缀或后缀@
字符todo@
后可能包含用户名- 注释中可能混有
:
或-
字符 - 支持多行
/* */
和/** */
注释
开箱即用的注释可以通过不同的约束条件到期:
- 通过
YYYY-MM-DD
格式的日期,与参考时间匹配 - 通过完整的github问题URL
- 通过语义版本约束,与Composer依赖匹配(通过
composer.lock
)
还有更多内置约束,但这些需要额外配置:
- 通过语义版本约束,与项目的参考版本配置匹配
- 通过语义版本约束,与Composer依赖匹配(通过
virtualPackages配置
) - 通过票据引用,与票据状态匹配(例如在github.com或JIRA通过配置)
以下是支持的不同注释变体示例:
// todo 2023-12-14
// @todo: 2023-12-14 修复它
// @todo 2023-12-14: 修复它
// XXX - 2023-12-14 修复它
// FIXME 2023-12-14 - 修复它
// TODO@staabm 2023-12-14 - 修复它
// TODO@markus: 2023-12-14 - 修复它
// TODO https://github.com/staabm/phpstan-todo-by/issues/91 当这个GitHub问题关闭时修复我
/*
* 其他文本
*
* @todo 2023-12-14 经典多行注释
* 更多注释数据
*/
// TODO: <1.0.0 这必须在第一个主要版本中完成
// TODO >123.4: 必须修复这个或提升版本
// TODO: phpunit/phpunit:<5 在更新到phpunit 5.x之前必须修复这个
// TODO@markus: phpunit/phpunit:5.3 当更新phpunit到5.3.x或更高版本时必须修复这个
// TODO: APP-123 当这个Jira票据关闭时修复它
// TODO: #123 当这个GitHub问题关闭时修复它
// TODO: GH-123 当这个GitHub问题关闭时修复它
// TODO: some-organization/some-repo#123 如果这个GitHub拉取请求关闭则更改我
配置
不可忽略的错误
默认情况下,扩展发出的错误是不可忽略的,因此它们不能被意外地放入基线中。
你可以在phpstan.neon
中使用配置选项来更改此行为:
parameters:
todo_by:
nonIgnorable: false # 默认为true
参考时间
默认情况下,日期todo注释是根据今天的日期进行检查的。
你可能对哪些注释将在未来7天内到期感兴趣,这可以通过referenceTime
选项配置。
你需要配置一个可被strtotime
解析的日期。
parameters:
todo_by:
# 任何strtotime()兼容的字符串
referenceTime: "now+7days"
使用环境变量尤其方便,这样你可以通过CLI传递参考日期:
parameters:
todo_by:
referenceTime: %env.TODOBY_REF_TIME%
TODOBY_REF_TIME="now+7days" vendor/bin/phpstan analyze
参考版本
默认情况下,版本todo注释是根据"nextMajor"
版本进行检查的。
它是通过获取最新的本地可用git标签并增加主版本号来确定的。
可以通过referenceVersion
选项配置行为。
可能的值是"nextMajor"
、"nextMinor"
、"nextPatch"
(这些将基于最新的本地git标签计算)或任何其他版本字符串,如"1.2.3"
。
parameters:
todo_by:
# "nextMajor"、"nextMinor"、"nextPatch"或版本字符串如"1.2.3"
referenceVersion: "nextMinor"
如上面"参考时间"段落所示,你甚至可以使用环境变量代替。
[!注意] 参考版本不适用于包版本todo注释,这些注释是根据
composer.lock
匹配的。
先决条件
确保在你的git克隆中可用标签,例如通过运行git fetch --tags origin
- 否则你可能会遇到"无法确定最新git标签"的错误。
在GitHub Action中,可以这样做:
- name: Checkout
uses: actions/checkout@v4
- name: Get tags
run: git fetch --tags origin
多GIT仓库支持
默认情况下,用于计算参考版本的最新git标签只会为所有被分析的文件获取一次。
可以通过singleGitRepo
选项配置此行为。
如果你使用git子模块,或者被分析的代码库由多个git仓库组成,
将singleGitRepo
选项设置为false
,这将为每个被分析的目录解析参考版本。
虚拟包
在PHPStan配置文件中,你可以定义额外的包,以匹配包版本todo注释。
parameters:
todo_by:
virtualPackages:
'staabm/mypackage': '2.1.0'
'staabm/my-api': '3.1.0'
在你的todo注释中像引用任何其他包一样引用这些虚拟包:
// TODO staabm/mypackage:2.2.0 一旦staabm/mypackage更新到2.2.0就删除以下函数
问题追踪器键支持
可选地,你可以配置此扩展来分析带有问题追踪器票据键的注释。 扩展获取问题追踪器API以获取问题状态。如果远程问题已解决,将报告该注释。
目前支持Jira、GitHub和YouTrack。
此功能默认禁用。要启用它,您必须将 ticket.enabled
参数设置为 true
。
您还需要设置以下参数:
parameters:
todo_by:
ticket:
enabled: true
# 以下之一: jira, github (区分大小写)
tracker: jira
# 区分大小写的状态名称列表。
# 只有具有这些状态之一的票据才被视为已解决。
# 支持的跟踪器: jira。其他跟踪器忽略此参数。
resolvedStatuses:
- Done
- Resolved
- Declined
# 如果您的票据键是 FOO-12345,则此值应为 ["FOO"]。
# 允许多个键前缀,例如 ["FOO", "APP"]。
# 只分析包含此前缀的键的注释。
# 支持的跟踪器: jira, youtrack。其他跟踪器忽略此参数。
keyPrefixes:
- FOO
jira:
# 例如 https://your-company.atlassian.net
server: https://acme.atlassian.net
# 请参阅下面的可能格式。
# 如果此值为空,将使用凭据文件。
credentials: %env.JIRA_TOKEN%
# 包含 Jira 凭据的文件路径。
# 请参阅下面的可能格式。
# 如果 credentials 参数不为空,将使用它而不是此文件。
# 此文件不能提交到存储库中!
credentialsFilePath: .secrets/jira-credentials.txt
github:
# 引用存储库的账户所有者。
defaultOwner: your-name
# 不带 .git 扩展名的存储库名称。
defaultRepo: your-repository
# GitHub 访问令牌
# 如果此值为空,将使用凭据文件。
credentials: null
# 包含 GitHub 访问令牌的文件路径。
# 如果 credentials 参数不为空,将使用它而不是此文件。
# 此文件不能提交到存储库中!
credentialsFilePath: null
youtrack:
# 例如 https://your-company.youtrack.cloud
server: https://acme.youtrack.cloud
# YouTrack 永久令牌
# 如果此值为空,将使用凭据文件。
credentials: %env.YOUTRACK_TOKEN%
# 包含 YouTrack 永久令牌的文件路径
# 如果 credentials 参数不为空,将使用它而不是此文件。
# 此文件不能提交到存储库中!
credentialsFilePath: .secrets/youtrack-credentials.txt
Jira 凭据
此扩展使用 Jira 的 REST API 获取票据状态。如果您的看板不是公开的,您需要配置有效的凭据。 支持以下身份验证方法:
我们建议您使用 OAuth 而不是基本身份验证,特别是如果您在 CI 中使用 phpstan。
有多种方法可以将凭据传递给此扩展。
您应该选择其中一种 - 如果您同时定义了两个参数,则只考虑 credentials
参数,忽略文件。
在环境变量中传递凭据
配置 credentials
参数以从环境变量读取值:
parameters:
todo_by:
ticket:
jira:
credentials: %env.JIRA_TOKEN%
根据所选的身份验证方法,其内容应为:
- 基于令牌的身份验证的访问令牌,例如
JIRA_TOKEN=ATATT3xFfGF0Gv_pLFSsunmigz8wq5Y0wkogoTMgxDFHyR...
- 基本身份验证的
<用户名>:<密码或API密钥>
,例如JIRA_TOKEN=john.doe@example.com:p@ssword
在文本文件中传递凭据
在项目目录(或计算机上的其他位置)创建文本文件,并将其路径放入配置中:
parameters:
todo_by:
ticket:
jira:
credentialsFilePath: path/to/file
记住不要将此文件提交到存储库中! 根据所选的身份验证方法,其值应为:
- 基于令牌的身份验证的访问令牌,例如
JATATT3xFfGF0Gv_pLFSsunmigz8wq5Y0wkogoTMgxDFHyR...
- 基本身份验证的
<用户名>:<密码或API密钥>
,例如john.doe@example.com:p@ssword
GitHub
同时支持 issues 和 pull requests。如果引用的 issue/PR 已关闭,则会报告该注释。 有多种方法可以引用 GitHub issue/PR:
仅数字
// TODO: #123 - fix me
// TODO: GH-123 - fix me
如果 defaultOwner
设置为 acme
,defaultRepo
设置为 hello-world
,则引用的 issue 解析为 acme/hello-world#123
。
所有者 + 存储库名称 + 数字
// TODO: acme/hello-world#123 - fix me
安装
要使用此扩展,请在 Composer 中安装它:
composer require --dev staabm/phpstan-todo-by
如果您还安装了 phpstan/extension-installer,那么一切就绪!
手动安装
如果您不想使用 phpstan/extension-installer
,请在项目的 PHPStan 配置中包含 extension.neon:
includes:
- vendor/staabm/phpstan-todo-by/extension.neon
常见问题
意外的 '"php" 版本要求 ">=XXX" 已满足' 错误
如果您过早地遇到这些错误,可能是由于 composer.json
文件中的版本约束不正确。
例如,php
版本约束 ^7.4
意味着 >=7.4.0 && <= 7.999999.99999
,
这意味着像 // TODO >7.5
这样的注释会发出错误。
对于 php
声明,建议使用带有固定上限的版本约束,例如 7.4.*
或 ^7 || <8.3
。
'无法确定最新的 git 标签' 错误
当 git 克隆中没有可用的 git 标签时,会抛出此错误。 按照上面"引用版本"章节中的描述获取 git 标签。
💌 给予一些爱
考虑支持该项目,这样我们就可以更快地为每个人做出更好的工具。