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 2.0 访问令牌
• 个人访问令牌
• 基本身份验证

我们建议您使用 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,那么一切就绪!

<details> <summary>手动安装</summary>

如果您不想使用 phpstan/extension-installer,请在项目的 PHPStan 配置中包含 extension.neon:

includes:
    - vendor/staabm/phpstan-todo-by/extension.neon

</details>

常见问题

意外的 '"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 标签。

💌 给予一些爱

考虑支持该项目,这样我们就可以更快地为每个人做出更好的工具。