Configuring Custom TODO Patterns Project-Wide in PhpStorm

1. TODO Comments as a Working Tool, Not Just a Note

In many projects, TODO comments are little more than a personal memory aid scattered through the code and never systematically reviewed again. Yet PhpStorm's TODO tool window offers a complete system for collecting, filtering and working through such markers project-wide. The key is to go beyond the default pair of TODO and FIXME and define your own, semantically clear patterns.

A pattern like MAGENTO-UPGRADE: immediately signals what it is about, while a generic TODO: has to be read first to recognize its category. In a codebase with several hundred TODO comments, this difference is what separates a searchable task catalog from an unstructured pile of notes that nobody can prioritize anymore.

2. How the Default TODO and FIXME System Works

PhpStorm recognizes TODO and FIXME by default in all supported file types without any configuration needed. Every comment starting with one of these keywords automatically appears in the TODO tool window, reachable via View, Tool Windows, TODO or the corresponding icon at the bottom of the editor. Recognition is based on regular expressions, viewable and editable under Settings, Editor, TODO.

FIXME is displayed with higher priority than TODO by default, visible through a red icon instead of a yellow one in the tool window. This prioritization is worth applying to custom patterns too, since it allows a rough sort by urgency before filtering by category at all. Anyone who understands the default patterns can build custom ones on the same principle and place them within the same priority logic.

3. Defining Custom Patterns: Syntax and Examples

Under Settings, Editor, TODO, a new pattern can be created via the plus icon. The configuration consists of a regular expression, a color and an icon assignment. For a pattern like MAGENTO-UPGRADE:, a simple expression that searches case-insensitively for the word at the start and optionally captures the text after the colon as description works well, so it reads directly in the tool window.

Sensible categories for a Magento codebase besides MAGENTO-UPGRADE include SECURITY: for security relevant spots, PERF: for known performance debt, and REFACTOR: for code that works but should be structurally improved. It is important to keep the pattern list deliberately small, since every additional category increases the effort to use it consistently across the team without falling back to the generic TODO.

Settings > Editor > TODO > + (add pattern)
Pattern:  \bMAGENTO-UPGRADE:.*
Case sensitive: no
Icon: pick a distinct icon/color, e.g. orange

Example in code:
// MAGENTO-UPGRADE: Check PHP 8.4 compatibility for array_key_first usage

4. Icon and Color Per Pattern for Fast Distinction

Every pattern in PhpStorm can get its own combination of icon and color, visible both directly in the editor's left margin and in the TODO tool window. This visual distinction is especially valuable when multiple categories occur in the same module: an orange symbol for MAGENTO-UPGRADE next to a red one for SECURITY lets you immediately spot, while scrolling through a file, what kind of task is waiting where.

Color choice should follow existing conventions, for example red for security critical and urgent points, orange for planned but not yet scheduled work, and blue for purely informational notes without immediate action required. This consistency reduces onboarding time for new team members, since a marker's meaning becomes clear from its color alone, before the text is even read.

5. TODO Tool Window: Grouping by Pattern Instead of File

The TODO tool window groups by file by default, which quickly becomes confusing in a large codebase because related tasks appear scattered across many files. Via the filter icon in the tool window, you can switch to a flat list or group by module instead, combined with the option to filter for a single pattern, for example showing only MAGENTO-UPGRADE entries.

In practice this means: instead of opening one file after another to check for TODO comments, you filter the tool window once by pattern and get a complete, project-wide list of exactly that category. During a PHP version upgrade, this makes it possible to see within seconds how many MAGENTO-UPGRADE spots remain open across the entire project, regardless of which module they sit in.

TODO Tool Window (View > Tool Windows > TODO)
  filter icon -> "Group by" -> Module instead of File
  filter icon -> pattern checkbox -> keep only "MAGENTO-UPGRADE" active
  Result: flat, project-wide list of all open MAGENTO-UPGRADE spots

6. Project-Wide Versus Global Configuration

PhpStorm distinguishes between IDE-wide TODO patterns, which apply to all projects on your own machine, and project specific patterns stored in the project configuration. For team projects the latter is the right approach: the pattern definitions end up in a configuration file inside the .idea folder and can be versioned, so every team member automatically sees the same categories the moment they open the project.

A common mistake is defining patterns only in your own local IDE settings. Recognition then works for that one person, but colleagues see plain unformatted text in the same code, without an icon and without an entry in the tool window. Before rolling out a new pattern to the whole team, it is worth a quick check whether the configuration file actually ends up in the repository and does not accidentally stay in the globally ignored user configuration.

7. Practical Example: MAGENTO-UPGRADE as a Migration Tool

When moving to a new Magento or PHP version, it is common to mark known trouble spots already during ongoing development, long before the actual upgrade is scheduled. A comment like MAGENTO-UPGRADE: check readonly properties for PHP 8.2 compatibility documents the knowledge exactly at the affected spot, instead of managing it in a separate ticket system that easily falls out of view.

When the upgrade actually comes up, the team filters the TODO tool window for the MAGENTO-UPGRADE pattern and gets a complete, code-near checklist. Every entry can be opened directly at the affected spot with a double click, making the context immediately visible without first reading an external ticket. Once the upgrade is finished, the completed comments are removed, automatically emptying the pattern again and leaving it ready for the next migration.

8. Combining Patterns With Scopes and Further Filters

The TODO tool window can additionally be combined with PhpStorm scopes, meaning user defined file sets covering, for example, only a specific module or only PHP files. Via the scope dropdown in the tool window, the display can be limited to a defined area, which is especially helpful in very large monorepos with many modules where thousands of entries would otherwise show at once.

Combined with pattern filtering, this produces a two-stage narrowing: first the scope to a specific module, then the pattern to a specific category. For a team that only wants to check checkout relevant modules before a release, this generates a precise list in seconds instead of manually searching through the entire project.

9. Limits, Pitfalls, and a Comparison of Pattern Types

As useful as custom patterns are, they do not replace a full ticket system for complex, multi-stage tasks. They are best suited for locally scoped, code-near notes that make sense in the context of that particular line. For larger initiatives with multiple participants and dependencies, an external tracking system remains the better choice, while TODO patterns bridge the gap between ticket and actual code.

Another pitfall is creeping clutter: without regular maintenance, outdated entries pile up that were resolved long ago but remain in the code. A quick check of the TODO tool window before every release, filtered by the most important patterns, prevents the list from turning into an unfiltered graveyard of data where real priorities are no longer recognizable.

10. Summary

11. FAQ: TODO Patterns in PhpStorm: The Key Facts at a Glance