[ ← blog / drupal ](/) Mar 24, 2026  ·  \#drupal  ·  2 min read 

# Catch @todo comments referencing the current issue



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`](https://github.com/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:

```php
// @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`:

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

```

When using the [Drupal GitLab CI templates](https://project.pages.drupalcode.org/gitlab_templates/jobs/phpstan/), 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](https://github.com/mglaman/phpstan-drupal#detecting-todo-comments-referencing-the-current-drupalorg-issue-contrib-ci).

 

  ![](/themes/custom/mglaman/images/headshot.webp)Thanks for reading

I write about Drupal, PHP, and the quiet infrastructure behind large sites — caching, config, and testing. New posts land every week or two.

 [Subscribe via RSS →](/rss.xml) [About me →](/about-me) 

 



 

  [← Older

Understanding Drupal: A Complete Guide to Caching Layers is now published!

 ](/blog/understanding-drupal-complete-guide-caching-layers-now-published) [Newer →

How Drupal's chained fast backend keeps APCu cache consistent across your web servers

 ](/blog/how-drupals-chained-fast-backend-keeps-apcu-cache-consistent-across-your-web-servers)