Inspired by parker-codes/todo-by I recently created phpstan-todo-by - a new PHPStan extension to check for TODO comments with expiration.

The announcement tweet / toot got a lot of attention and I received a lot of positive feedback.

The project already got 50 stars within the first week after announcement.

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.

<?php

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

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

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

// TODO: 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: #123 fix it when this GitHub issue is closed
// TODO: some-organization/some-repo#123 change me if this GitHub pull request 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)
  • by ticket reference, matched against the status of a ticket (e.g. in JIRA, GitHub issues, YouTrack)

Find more details and configuration options in the projects README.

Give back

In case you find my PHPStan contributions and/or this tool useful, please consider supporting my open source work.

Found a bug? Please help improve this article.

<
Previous Post
Contribution Summary 2023
>
Next Post
PHPStan tailored to your needs