Phpstan Todo By Laravel Package

Product Decisions This Supports

• Enforcing "expiring" TODOs and tech-debt hygiene in CI: phpstan-todo-by is a PHPStan rule that fails builds when a TODO/FIXME exceeds a due date or references a closed issue. This turns "we'll clean it up later" into a tracked, testable commitment—useful as a lightweight debt-governance policy without buying a SaaS tool.
• Build vs. buy: It's a single-purpose static-analysis rule rather than a platform. Adopt it where you already run PHPStan (very common in Laravel), effectively "buying" (via Composer) a small enforcement mechanism instead of building custom CI scripts to grep for stale TODOs.
• Release 0.3.5 feature—optional GitHub issue lookups: The new ability to turn off GitHub issue URL fetches supports decisions about CI topology and supply-chain/network posture:
  • Run the rule without outbound calls to GitHub—important for air-gapped CI, ephemeral runners, forks, and environments where secrets/tokens shouldn't be exposed to PR builds.
  • Avoid GitHub API rate limits and flaky network dependencies in the critical build path.
  • Choose per-pipeline behavior: enforce date-based TODOs everywhere, but only enable issue-status checks where a token and connectivity exist (e.g., scheduled/nightly jobs).
• Roadmap signal for platform/DevEx teams: A low-risk, active OSS dependency with steady dependabot maintenance. Low integration cost, no breaking changes in this release; can be piloted on one repo before standardizing across a Laravel portfolio.
• Use cases: date-bound deprecation shims, temporary feature flags/workarounds with a removal date, "remove this when issue #123 is closed" comments, PR-review automation for stale debt, and release/upgrade cleanup tracking.

When to Consider This Package

Consider adoption when:

• You already run PHPStan in CI (required—it's a PHPStan extension, not a standalone tool), typically alongside Larastan in Laravel projects.
• You want a cheap, deterministic guardrail against permanent TODOs and forgotten workarounds, without adopting a new dashboard or SaaS.
• Your team writes date-scoped or ticket-scoped TODOs and you can agree on a comment convention.
• You need CI that works offline or without GitHub credentials—0.3.5 makes this materially easier via the ability to disable GitHub issue fetching.
• You're comfortable with Composer-based OSS dependencies and a small, active maintainer footprint.

Look elsewhere or defer when:

• You don't use PHPStan, or static analysis is not part of your pipeline—the rule has no enforcement point.
• You need cross-language debt tracking, dashboards, ownership, or SLA reporting (consider a dedicated issue tracker, SonarQube-style platform, or custom reporting).
• Your policy is "no TODOs at all" or you rely on runtime enforcement—this is static analysis only.
• CI must remain completely network-isolated with no GitHub API access at all and you also want issue-status checks—date-based checks work, but issue lookups would need to be disabled, so plan that trade-off.
• You require vendor support/SLAs; this is community OSS.

How to Pitch It (Stakeholders)

For executives / engineering leadership: We can adopt a small open-source PHPStan rule that makes temporary TODO/FIXME comments expire. If a TODO has a date that's passed, or references a GitHub issue that's been closed, the build fails—so debt gets cleaned up instead of accumulating silently. Integration cost is low because we already run PHPStan, and it's not a new platform, vendor contract, or runtime dependency. Release 0.3.5 is a maintenance release with one practical improvement: we can turn off GitHub issue-URL lookups, which lets us run the rule in restricted or air-gapped CI and avoids rate-limit/network flakiness. No breaking changes; recommend a pilot on one Laravel repo, then standardize if the signal-to-noise is good.

For engineering: Add staabm/phpstan-todo-by as a dev dependency and enable it in phpstan.neon. Agree on a convention (e.g., // TODO: 2025-12-31 ... or // TODO: https://github.com/org/repo/issues/123 ...). Use the new 0.3.5 option to disable GitHub fetches in PR/ephemeral CI; enable issue checks only in jobs with a token and network access. Expect deterministic, fast checks, with the main operational decision being whether issue-status verification runs per-PR or on a schedule.