Repository navigation
Conversation
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
force-pushed
the
feat/add-throws-tag-rector
branch
from
November 18, 2026 07:34
397b8d7 to
9fcc7f8
Compare
yoannblot
marked this pull request as ready for review
November 18, 2026 07:36
Member
|
Hi, thanks for suggestion. We had similar rule in the past, but it struggled with finding the right limit:
It caused more troubles than added value, so we removed it. In the end this is better land in user land as custom rules 👍 |
Author
|
Thanks @TomasVotruba for the quick and clear answer, that makes sense. 👍 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
AddThrowsTagRector(TypeDeclarationDocblocks): adds a@throwstag 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:
throw;@throwsin its own docblock (run the rule again to climb a call chain one level at a time);catchorfinallythrows; thetrybody is only covered by its own catches.Skipped:
@throwsof the same or a broader type, or inherited from the overridden parent/interface method;$this->foo(...)), which execute nothing;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
LogicExceptioneverywhere). Users enable it withruleWithConfiguration().rector.registerRectorwould flag it, sophpstan.neongets one more path in the existing opt-out list, next toNullToStrictStringFuncCallArgRector. Happy to move it elsewhere if you prefer another approach.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$argvones inscripts/rector-hotspot-profile.phpande2e/e2eTestRunner.php, already onmain.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.