phpstan-todo-by: A Practical PHPStan Extension
Overview
phpstan-todo-by is an innovative extension for PHPStan users, designed to track TODO and similar annotations in your code. The extension's unique twist is its ability to turn these comments into warnings or errors once certain conditions are met, such as hitting a specific date, meeting a software version requirement, or closing an issue tracker ticket. Inspired by parker-codes/todo-by, this tool brings a level of automation to ensure that temporary comments in your code don't linger indefinitely.
Functionality
The core functionality of phpstan-todo-by is to highlight comments marked with TODO-like keywords, converting them into actionable errors within PHPStan under defined circumstances. For instance, if a comment specifies a future date like // TODO: 2023-12-14, PHPStan will generate an error once December 14, 2023, is reached, reminding developers to address the issue noted in the comment.
The extension accommodates various formats for TODO comments, including:
- Date-specific comments: such as
// @todo 2023-12-14. - Comments linked to version constraints: e.g.,
// TODO: <1.0.0. - Comments tied to issue tracker status: when the ticket is closed, the comment triggers a PHPStan error.
Usage Examples
Here's how phpstan-todo-by could be used in a codebase:
// TODO: 2023-12-14 This comment turns into a PHPStan error as of 14th December 2023
function doFoo() { /* ... */ }
// FIXME: phpunit/phpunit:5.3 This has to be fixed when updating phpunit to 5.3.x or higher
function doFooBar() { /* ... */ }
Flexibility and Configuration
phpstan-todo-by offers flexible configuration options:
-
Non-Ignorable Errors: By default, errors emitted cannot be ignored, preventing them from slipping into the baseline unnoticed. However, you can configure this setting if necessary.
-
Reference Time: Set an arbitrary date against which date-related todos will be checked, allowing for future-planning capabilities.
-
Reference Version: Define how version-related comments should be interpreted—against a specific software release or semantic versioning constraint.
-
Virtual Packages & Multiple Repositories: Additional package references and support for multiple Git repositories are configurable for complex projects.
-
Issue Tracker Integration: Optionally connect the extension with Jira, GitHub, or YouTrack for seamless error reporting tied to issue statuses.
Installation
To integrate phpstan-todo-by into your project, simply run:
composer require --dev staabm/phpstan-todo-by
If using phpstan/extension-installer, no further setup is needed. Otherwise, manually include vendor/staabm/phpstan-todo-by/extension.neon in your PHPStan configuration.
Conclusion
phpstan-todo-by is a robust tool in ensuring that temporary code comments do not become permanent fixtures in your codebase. By leveraging conditions like dates and issue tracker statuses, it helps maintain code health and encourages timely refactoring. Whether you're managing a large codebase or a dynamic development environment, phpstan-todo-by offers a blend of simplicity and functionality to ensure your TODO comments maintain their intended brevity.