Skip to content

[TypeDeclarationDocblocks] Add AddThrowsTagRector - #9002

Closed
yoannblot wants to merge 1 commit into
rectorphp:mainfrom
yoannblot:feat/add-throws-tag-rector
Closed

yoannblot wants to merge 1 commit into
rectorphp:mainfrom
yoannblot:feat/add-throws-tag-rector

Conversation

@yoannblot

@yoannblot yoannblot commented Nov 18, 2026 •

Copy link
Copy Markdown

Summary

Adds AddThrowsTagRector (TypeDeclarationDocblocks): adds a @throws tag for every checked exception a method lets escape.

 final class SomeClass
 {
+    /**
+     * @throws \RuntimeException
+     */
     public function run(): void
     {
         throw new \RuntimeException('boom');
     }
 }

What counts as escaping:

  • a direct throw;
  • a called method, static method or constructor that declares @throws in its own docblock (run the rule again to climb a call chain one level at a time);
  • what a catch or finally throws; the try body is only covered by its own catches.

Skipped:

  • exceptions already documented, by a @throws of the same or a broader type, or inherited from the overridden parent/interface method;
  • exceptions thrown inside a nested closure, arrow function or class;
  • first-class callables ($this->foo(...)), which execute nothing;
  • the exceptions (and their subclasses) listed in the rule configuration, for unchecked exceptions such as LogicException.

Configuration and registration

The rule is configurable: the list of unchecked exceptions is project specific, so there is no sensible default. For the same reason it is not registered in any set or level (with an empty list it would document LogicException everywhere). Users enable it with ruleWithConfiguration().

rector.registerRector would flag it, so phpstan.neon gets one more path in the existing opt-out list, next to NullToStrictStringFuncCallArgRector. Happy to move it elsewhere if you prefer another approach.

$rectorConfig->ruleWithConfiguration(AddThrowsTagRector::class, [
    LogicException::class,
    ValueError::class,
]);

Known limits

Not handled for now: plain functions (Function_), nullsafe method calls ($a?->foo()) and function calls that declare @throws.

Tests

18 fixtures under rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddThrowsTagRector. composer fix-cs, PHPStan and the rule tests pass locally. The only PHPStan errors left are the $argv ones in scripts/rector-hotspot-profile.php and e2e/e2eTestRunner.php, already on main.

The rule was first written and used in a private codebase, then ported here. It was written with Claude Code, and reviewed by Claude subagents before opening this PR.

Adds an opt-in rule that adds a @throws tag for every checked exception escaping a method. The unchecked exceptions are project specific, so the rule has no default list and lives in its own opt-in set, enabled with withPreparedSets(throwsTag: true).
@yoannblot
yoannblot force-pushed the feat/add-throws-tag-rector branch from 397b8d7 to 9fcc7f8 Compare November 18, 2026 07:34
@yoannblot
yoannblot marked this pull request as ready for review November 18, 2026 07:36
@TomasVotruba

Copy link
Copy Markdown
Member

Hi, thanks for suggestion. We had similar rule in the past, but it struggled with finding the right limit:

  • which exceptions to add
  • how to handle removed exception
  • should copy-paste from parent/interface (often Doctrine case)
  • should copy-paste from nested calls that have @throws

It caused more troubles than added value, so we removed it.

In the end this is better land in user land as custom rules 👍

@yoannblot

Copy link
Copy Markdown
Author

Thanks @TomasVotruba for the quick and clear answer, that makes sense. 👍
The unchecked exception list and the nested calls were the hard part for me too, and I could only make them tractable by pushing the choice to the config (and skipping what the parent/interface already documents). I'll keep it as a custom rule on our side.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants