staabm/phpstan-todo-by

维护者

详细信息

github.com/staabm/phpstan-todo-by

源代码

问题

资助包维护！
staabm

安装次数: 333,462

依赖者: 16

建议者: 1

安全: 0

星标: 173

关注者: 3

分支: 4

公开问题: 4

类型：phpstan-extension

0.1.31 2024-09-16 15:02 UTC

Requires

Requires (Dev)

MIT 2715e6d792de8e72cf1eae2ea1bb87c55d93618b

commentsstatic analysisdevexpirationPHPStanphpstan-extension

This package is auto-updated.

Last update: 2024-09-16 15:02:49 UTC

README

PHPStan 扩展，用于检查带有过期时间的 TODO/FIXME/XXX 注释。受 parker-codes/todo-by 启发。

示例

主要思想是，当满足条件时（例如，日期到达，版本满足，问题跟踪器票据关闭），源代码中的注释将转换为 PHPStan 错误。

<?php

// TODO: 2023-12-14 This comment turns into a PHPStan error as of 14th december 2023
function doFoo() { /* ... */ }

// TODO https://github.com/staabm/phpstan-todo-by/issues/91 fix me when this GitHub issue is closed
class FooClass {}

// TODO: <1.0.0 This has to be in the first major release of this repo
function doBar() { /* ... */ }

// FIXME: phpunit/phpunit:5.3 This has to be fixed when updating phpunit to 5.3.x or higher
function doFooBar() { /* ... */ }

// XXX: php:8 drop this polyfill when php 8.x is required

// TODO: APP-2137 A comment which errors when the issue tracker ticket gets resolved
function doBaz() { /* ... */ }

支持的 todo 格式

todo 注释也可以仅由一个约束组成，没有文本，如 // @todo 2023-12-14。当在日期后给出文本时，此文本将被用于 PHPStan 错误消息。

  • 关键字 todo、TODO、tOdO、FIXME、XXX 不区分大小写
  • todo 关键字可以后缀或前缀一个 @ 字符
  • 用户名可能位于 todo@ 之后
  • 注释可能与 : 或 - 字符混合
  • 支持多行 /* */ 和 /** */ 注释

默认 注释可以通过不同的约束过期

  • 通过日期，格式为 YYYY-MM-DD，与 参考时间 匹配
  • 通过完整的 GitHub 问题 URL
  • 通过语义版本约束与 Composer 依赖项匹配（通过 composer.lock）

还有更多内置约束，但它们需要额外的配置

查看支持的注释变体的示例

// todo 2023-12-14
// @todo: 2023-12-14 fix it
// @todo 2023-12-14: fix it
// XXX - 2023-12-14 fix it
// FIXME 2023-12-14 - fix it

// TODO@staabm 2023-12-14 - fix it
// TODO@markus: 2023-12-14 - fix it

// TODO https://github.com/staabm/phpstan-todo-by/issues/91 fix me when this GitHub issue is closed

/*
 * other text
 *
 * @todo 2023-12-14 classic multi line comment
 *   more comment data
 */

// TODO: <1.0.0 This has to be in the first major release
// TODO >123.4: Must fix this or bump the version

// TODO: phpunit/phpunit:<5 This has to be fixed before updating to phpunit 5.x
// TODO@markus: phpunit/phpunit:5.3 This has to be fixed when updating phpunit to 5.3.x or higher

// TODO: APP-123 fix it when this Jira ticket is closed
// TODO: #123 fix it when this GitHub issue is closed
// TODO: GH-123 fix it when this GitHub issue is closed
// TODO: some-organization/some-repo#123 change me if this GitHub pull request is closed

配置

不可忽略的错误

默认情况下，由扩展发出的错误是不可忽略的，因此它们不会意外地放入基线。您可以通过您的 phpstan.neon 中的配置选项更改此行为。

parameters:
    todo_by:
        nonIgnorable: false # default is true

参考时间

默认情况下，日期 todo 注释与今天的日期进行比较。

您可能想知道哪些注释将在接下来的 7 天内过期，这可以通过 referenceTime 选项进行配置。您需要配置一个可由 strtotime 解析的日期。

parameters:
    todo_by:
        # any strtotime() compatible string
        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" or a version string like "1.2.3"
        referenceVersion: "nextMinor"

如上所述的 "参考时间" 段落中所示，您甚至可以使用环境变量。

注意

参考版本不应用于与composer.lock匹配的包版本待办评论。

先决条件

确保在您的git clone中可使用标签，例如，通过运行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配置文件中，您可以定义额外的包，以匹配包版本待办评论。

parameters:
    todo_by:
        virtualPackages:
            'staabm/mypackage': '2.1.0'
            'staabm/my-api': '3.1.0'

像其他包一样在待办评论中引用这些虚拟包

// TODO staabm/mypackage:2.2.0 在staabm/mypackage更新到2.2.0后删除以下函数

问题跟踪器密钥支持

可选地，您可以配置此扩展以分析带有问题跟踪器票证的注释。扩展会获取问题跟踪器API以获取问题状态。如果远程问题已解决，则将报告该注释。

目前支持Jira、GitHub和YouTrack。

此功能默认禁用。要启用它，您必须将ticket.enabled参数设置为true。您还需要设置以下参数

parameters:
    todo_by:
        ticket:
            enabled: true

            # one of: jira, github (case-sensitive)
            tracker: jira

            # a case-sensitive list of status names.
            # only tickets having any of these statuses are considered resolved.
            # supported trackers: jira. Other trackers ignore this parameter.
            resolvedStatuses:
                - Done
                - Resolved
                - Declined

            # if your ticket key is FOO-12345, then this value should be ["FOO"].
            # multiple key prefixes are allowed, e.g. ["FOO", "APP"].
            # only comments with keys containing this prefix will be analyzed.
            # supported trackers: jira, youtrack. Other trackers ignore this parameter.
            keyPrefixes:
                - FOO

            jira:
                # e.g. https://your-company.atlassian.net
                server: https://acme.atlassian.net

                # see below for possible formats.
                # if this value is empty, credentials file will be used instead.
                credentials: %env.JIRA_TOKEN%

                # path to a file containing Jira credentials.
                # see below for possible formats.
                # if credentials parameter is not empty, it will be used instead of this file.
                # this file must not be committed into the repository!
                credentialsFilePath: .secrets/jira-credentials.txt

            github:
                # The account owner of referenced repositories.
                defaultOwner: your-name

                # The name of the repository without the .git extension.
                defaultRepo: your-repository

                # GitHub Access Token
                # if this value is empty, credentials file will be used instead.
                credentials: null

                # path to a file containing GitHub Access Token.
                # if credentials parameter is not empty, it will be used instead of this file.
                # this file must not be committed into the repository!
                credentialsFilePath: null

            youtrack:
                # e.g. https://your-company.youtrack.cloud
                server: https://acme.youtrack.cloud

                # YouTrack permanent token
                # if this value is empty, credentials file will be used instead.
                credentials: %env.YOUTRACK_TOKEN%

                # path to a file containing a YouTrack permanent token
                # if credentials parameter is not empty, it will be used instead of this file.
                # this file must not be committed into the repository!
                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...
  • <username>:<passwordOrApiKey>对于基本认证，例如[email protected]:p@ssword
在文本文件中传递凭证

在您的项目目录中创建文本文件（或在您的计算机上的任何其他位置），并将其路径放入配置中

parameters:
    todo_by:
        ticket:
            jira:
                credentialsFilePath: path/to/file

请记住不要将此文件提交到存储库！根据选择的认证方法，其值应为

  • 基于令牌认证的访问令牌，例如JATATT3xFfGF0Gv_pLFSsunmigz8wq5Y0wkogoTMgxDFHyR...
  • <username>:<passwordOrApiKey>对于基本认证，例如[email protected]:p@ssword

GitHub

支持问题和拉取请求。如果引用的问题/PR已关闭，则将报告注释。

仅数字
// TODO: #123 - fix me
// TODO: GH-123 - fix me

如果defaultOwner设置为acme，且defaultRepo设置为hello-world，则引用的问题解析为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，请将 extension.neon 文件包含在您项目的 PHPStan 配置中

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

常见问题解答（FAQ）

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

💌 回馈一些爱心

考虑支持此项目，这样我们就能更快地为大家制作出更好的工具。