When making code changes or fixing issues, it's easy to leave @todo comments behind. Sometimes they mark areas waiting on an upstream fix, sometimes they're reminders that never got revisited. Either way, they accumulate — and the ones tied to the specific issue you're working on should be resolved before the MR merges.

phpstan-drupal 2.0.12 adds TodoCommentWithIssueUrlRule to catch this in the GitLab CI jobs on Drupal.org.

This rule is inspired by staabm/phpstan-todo-by, which handles expiring todos by date, version constraint, and issue tracker status. It doesn't currently support custom issue fetchers or alternative detection mechanisms, such as matching ticket IDs to branch names — but that flexibility could make its way there someday.

What it does

The rule scans @todo comments for Drupal.org issue URLs and compares them against the current merge request's issue NID:

// @todo Remove once https://drupal.org/i/3456789 is resolved.

Both drupal.org/i/{nid} and drupal.org/project/{project}/issues/{nid} URL formats are matched.

The rule auto-detects the issue NID from standard GitLab CI environment variables — either CI_MERGE_REQUEST_SOURCE_BRANCH_NAME (e.g. 3456789-my-feature) or CI_MERGE_REQUEST_SOURCE_PROJECT_PATH (e.g. issue/mymodule-3456789). When neither variable is set — local runs, non-MR pipelines — the rule is silent.

Opting in

The rule is not registered by default. Add it to your project's phpstan.neon:

rules:
    - mglaman\PHPStanDrupal\Rules\Drupal\TodoCommentWithIssueUrlRule

When using the Drupal GitLab CI templates, adding extra rules requires a custom phpstan.neon that includes the default configuration — the template variables don't support it directly. The GitLab Templates PHPStan docs cover the setup.

Full documentation is in the phpstan-drupal README.