Download the PHP package staabm/phpstan-todo-by without Composer

phpstan-todo-by: comments with expiration

PHPStan extension to check for TODO comments with expiration. Inspired by parker-codes/todo-by.

Examples

The main idea is, that comments within the source code will be turned into PHPStan errors when a condition is satisfied, e.g. a date reached, a version met, a issue tracker ticket is closed.

Supported todo formats

A todo comment can also consist of just a constraint without any text, like // @todo 2023-12-14. When a text is given after the date, this text will be picked up for the PHPStan error message.

• the todo, TODO, tOdO keyword is case-insensitive
• the todo keyword can be suffixed or prefixed by a @ character
• a username might be included after the todo@
• the comment might be mixed with : or - characters
• multi line /* */ and /** */ comments are supported

The comment can expire by different constraints, examples are:

• by date with format of YYYY-MM-DD matched against the reference-time
• by a semantic version constraint matched against the projects reference-version
• by a semantic version constraint matched against a Composer dependency (via composer.lock or virtualPackages config)
• by ticket reference, matched against the status of a ticket (e.g. in github.com or JIRA)

see examples of different comment variants which are supported:

Configuration

Non-ignorable errors

Errors emitted by the extension are non-ignorable by default, so they cannot accidentally be put into the baseline. You can change this behaviour with a configuration option within your phpstan.neon:

Reference time

By default date-todo-comments are checked against todays date.

You might be interested, which comments will expire e.g. within the next 7 days, which can be configured with the referenceTime option. You need to configure a date parsable by strtotime.

It can be especially handy to use a env variable for it, so you can pass the reference date e.g. via the CLI:

TODOBY_REF_TIME="now+7days" vendor/bin/phpstan analyze

Reference version

By default version-todo-comments are checked against "nextMajor" version. It is determined by fetching the latest local available git tag and incrementing the major version number.

The behaviour can be configured with the referenceVersion option. Possible values are "nextMajor", "nextMinor", "nextPatch" - which will be computed based on the latest local git tag - or any other version string like "1.2.3".

As shown in the "Reference time"-paragraph above, you might even use a env variable instead.

[!NOTE] The reference version is not applied to package-version-todo-comments which are matched against composer.lock instead.

Prerequisite

Make sure tags are available within your git clone, e.g. by running git fetch --tags origin - otherwise you are likely running into a 'Could not determine latest git tag' error.

In a GitHub Action this can be done like this:

Multiple GIT repository support

By default the latest git tag to calculate the reference version is fetched once for all files beeing analyzed.

This behaviour can be configured with the singleGitRepo option.

In case you are using git submodules, or the analyzed codebase consists of multiple git repositories, set the singleGitRepo option to false which resolves the reference version for each directory beeing analyzed.

Virtual packages

Within the PHPStan config file you can define additional packages, to match against package-version-todo-comments.

Reference these virtual packages like any other package in your todo-comments:

// TODO staabm/mypackage:2.2.0 remove the following function once staabm/mypackage is updated to 2.2.0

Issue tracker key support

Optionally you can configure this extension to analyze your comments with issue tracker ticket keys. The extension fetches issue tracker API for issue status. If the remote issue is resolved, the comment will be reported.

Currently, Jira, GitHub and YouTrack are supported.

This feature is disabled by default. To enable it, you must set ticket.enabled parameter to true. You also need to set these parameters:

Jira Credentials

This extension uses Jira's REST API to fetch ticket's status. If your board is not public, you need to configure valid credentials. These authentication methods are supported:

• OAuth 2.0 Access Tokens
• Personal Access Tokens
• Basic Authentication

We recommend you use OAuth over basic authentication, especially if you use phpstan in CI. There are multiple ways to pass your credentials to this extension. You should choose one of them - if you define both parameters, only credentials parameter is considered and the file is ignored.

Pass credentials in environment variable

Configure credentials parameter to read value from environment variable:

Depending on chosen authentication method its content should be:

• Access Token for token based authentication, e.g. JIRA_TOKEN=ATATT3xFfGF0Gv_pLFSsunmigz8wq5Y0wkogoTMgxDFHyR...
• <username>:<passwordOrApiKey> for basic authentication, e.g. [email protected]:p@ssword

Pass credentials in text file

Create text file in your project's directory (or anywhere else on your computer) and put its path into configuration:

Remember not to commit this file to repository! Depending on chosen authentication method its value should be:

• Access Token for token based authentication, e.g. JATATT3xFfGF0Gv_pLFSsunmigz8wq5Y0wkogoTMgxDFHyR...
• <username>:<passwordOrApiKey> for basic authentication, e.g. [email protected]:p@ssword

GitHub

Both issues and pull requests are supported. The comment will be reported if the referenced issue/PR is closed. There are multiple ways to reference GitHub issue/PR:

Only number

If the defaultOwner is set to acme and defaultRepo is set to hello-world, the referenced issue is resolved to acme/hello-world#123.

Owner + repository name + number

Installation

To use this extension, require it in Composer:

If you also install phpstan/extension-installer then you're all set!

FAQ

Unexpected '"php" version requirement ">=XXX" satisfied' error

If you get this errors too early, it might be caused by wrong version constraints in your composer.json file. A php version constraint of e.g. ^7.4 means >=7.4.0 && <= 7.999999.99999, which means comments like // TODO >7.5 will emit an error.

For the php declaration, it is recommended to use a version constraint with a fixed upper bound, e.g. 7.4.* or ^7 || <8.3.

'Could not determine latest git tag' error

This error is thrown, when no git tags are available within your git clone. Fetch git tags, as described in the "Reference version"-chapter above.

💌 Give back some love

Consider supporting the project, so we can make this tool even better even faster for everyone.