Rector to automatically remove return type that the function never returns

[calebdw]

Feature Request

Hello!

I'm trying to convert most of my classes to final, and PHPStan is starting to complain about methods that have return types that are never returned (which is a good thing):

Method <class>::definition() never returns Illuminate\\Database\\Query\\Builder so it can be removed from the return type.

However, it would be awesome if Rector could detect this as well and automatically remove it for me.

For reference, here's the PHPStan rules that detect this:

Diff

-public function definition(): Builder|string
+public function definition(): string

Thanks!

[calebdw]

I have a draft version coming along nicely! Stay tuned...

[calebdw]

@samsonasik, is Rector able to update PHPDocs (e.g., @return Builder<...>|Model) or is it just native return types?

[calebdw]

Here's a nice table reference---only the safe methods will be updated

🟢 SAFE (No Risk)

Visibility	Parent Method	Final Class	Method	Notes
Private	Any	Any	N/A	No inheritance concerns — no overriding possible
Protected	None	Final	Any	No child classes possible, so return type removal is safe
Protected	Has Parent	Final	Any	No child classes possible, so return type removal is safe
Public	None	Final	Any	No child classes possible, so return type removal is safe
Public	Has Parent	Final	Any	No child classes possible, so return type removal is safe
Any	Any	Any	Final	Method can’t be overridden, so safe regardless of class finality

⚠️ CAUTION (Medium Risk)

Visibility	Parent Method	Final Class	Method	Notes
Protected	None	Non-final	N/A	Future children can override, may conflict with broader/narrower types
Protected	None	Non-final	Abstract	Future children must implement, so removing type changes their contract
Public	None	Non-final	N/A	Future children can override, may conflict with broader/narrower types
Public	None	Non-final	Abstract	Future children must implement, so removing type changes their contract

❌ RISKY (High Risk)

Visibility	Parent Method	Final Class	Method	Notes
Protected	Has Parent	Non-final	N/A	Blocks future children from returning anything outside the parent's original union
Protected	Has Parent	Non-final	Abstract	Forces children to implement with narrower return possibilities
Public	Has Parent	Non-final	N/A	Blocks future children from returning anything outside the parent's original union
Public	Has Parent	Non-final	Abstract	Forces children to implement with narrower return possibilities

[samsonasik]

Closing per rectorphp/rector-src#7147 (comment)

[github-actions]

This issue has been automatically locked because it has been closed for 150 days. Please open a new issue if you have a similar problem.