Phpstan Todo By Laravel Package

Technical Evaluation

Architecture fit staabm/phpstan-todo-by is a PHPStan extension, not a Laravel package proper — it hooks into PHPStan's rule pipeline at static-analysis time and carries no runtime footprint. In a Laravel context that means it lands alongside Larastan and inherits whatever PHPStan level and config the team already runs. Its function is narrow and well-bounded: it converts TODO, FIXME, @todo and similar markers into analysable debt, optionally validating that referenced issue URLs exist and that date-based todos (TODO by 2025-01-01) have not lapsed. The 0.3.5 release adds a toggle to disable GitHub issue URL fetching, which removes the only outbound network dependency in the tool.

Integration feasibility Low friction. composer require --dev staabm/phpstan-todo-by plus a phpstan.neon include, then it runs as part of the existing phpstan analyse invocation. No service container bindings, no migrations, no config publishing, no middleware. Works on the same PHP versions PHPStan supports, so it slots into existing CI images without new tooling.

Technical risk

• Pre-1.0 versioning (0.x): semver stability is not guaranteed; minor bumps may carry breaking changes to rule identifiers or config keys. Pin to a minor range and review changelogs on upgrade.
• Network egress in CI: prior to 0.3.5, GitHub issue URL validation made outbound calls during analysis. That is a real operational hazard — rate limiting (unauthenticated GitHub API is severely throttled), timeouts, and non-deterministic builds. 0.3.5's off-switch is the single most important risk-reducer in this release.
• False-positive debt enforcement: if the rule is enabled at error level against a legacy codebase, the build fails on day one with hundreds of pre-existing todos. This is a policy/config problem, not a package problem, but it is the most common way rollouts stall.
• Low blast radius: worst case the rule is removed from phpstan.neon; nothing in production breaks.

Key questions

1. What is the exact config parameter name for the new URL-fetch toggle, and does it default to on or off? Confirm against the 0.3.5 README before writing it into CI config.
2. Do we want issue-URL validation at all, or is comment-format and date-expiry checking sufficient? Answer determines whether the toggle matters to us.
3. Who owns the TODO debt policy — is this advisory (warning level) or blocking (error level)?
4. Does our CI have a GitHub token available if we do enable URL fetching, and what is our tolerance for an external API in the build path?
5. Which PHPStan level and Larastan version are in use, and does the extension's rule set overlap with existing custom rules?

Integration Approach

Stack fit Add as a require-dev dependency in Laravel applications and in shared internal packages. It pairs naturally with Larastan: Larastan covers type and framework correctness, phpstan-todo-by covers debt hygiene. No production dependency, so composer install --no-dev in deploy images is unaffected.

Migration path

1. Install and register the extension in phpstan.neon with URL fetching disabled (per 0.3.5) to keep builds hermetic.
2. Run once locally to size the existing todo population.
3. Generate a PHPStan baseline to freeze current debt, so the rule only fires on newly introduced todos.
4. Promote the rule from warning to error in CI once the baseline is stable.

Compatibility Requires a PHPStan version in the extension's supported range — verify against the current Larastan-pinned PHPStan before installing, since Larastan constrains PHPStan's major version. PHP 8.x only in practice. The GitHub-fetch toggle is additive and backwards compatible; no config migration needed from 0.3.4.

Sequencing Pilot in a single high-traffic application for one sprint → confirm signal quality and CI timing impact → adopt in shared packages → roll out org-wide via a reusable CI workflow and a common phpstan.neon fragment. Keep the extension version pinned in lockfile; upgrade deliberately, not via auto-merge on 0.x.

Operational Impact

Maintenance Minimal. The extension has no runtime surface, no database, no scheduled work. Recurring cost is dependency-bump review — this release alone shows five Dependabot action bumps and one pinning change, indicating active maintenance and automated hygiene. Assign ownership of the phpstan.neon fragment to the platform/tooling team.

Support Support burden is developer-facing only: "why did my build fail on a TODO comment?" Answer is a one-line policy doc plus the baseline escape hatch. No on-call implications.

Scaling Scales linearly with analysis time and is negligible against Larastan's own cost. Disabling URL fetching (0.3.5) removes the one component that would degrade at scale — a monorepo with hundreds of issue references would otherwise issue hundreds of API calls per run and hit rate limits.

Failure modes

• GitHub API rate limit or timeout → nondeterministic red builds. Mitigated by 0.3.5's toggle; recommend keeping it off unless URL validation is explicitly wanted.
• Upstream 0.x breaking change on a version bump → rule silently stops matching or config key errors out. Mitigate with pinned minor versions and CI config validation.
• Unbaselined legacy debt → immediate build failure on adoption. Mitigate with baseline-first rollout.
• Overly strict date-based todos expiring mid-sprint → unexpected red builds; treat date-expiry rules as warning-level initially.

Ramp-up Under an hour for a developer familiar with PHPStan config. The only non-obvious step is baselining. Recommend a short internal note covering: install command, the phpstan.neon include, the URL-fetch toggle, baseline generation, and the TODO format convention the team agrees to standardise on.