#3191·phpstan

Docblock emitting error that source code wouldn't

Author: deleugpnCreated Apr 20, 2020Updated Sep 29, 2026
Labelsbug

Bug report

As reported here and here, a mismatch in docblock may emit an error that the actual source code wouldn't. This issue can (and have been) fixed on Carbon itself as it can be seen on the linked PR.

However, I'd like to raise the question of whether it would be easy or worth it to avoid this case being an error in the first place. My reasoning is the following: docblock helps a lot to describe something that the actual code cannot (e.g. string[]). However, if the docblock describes a signature in one way and the code describes in another, using it in the way that the actual code describes the signature doesn't seem a valid error, at least at first glance. Shouldn't the docblock error be silenced since the interface clearly allows it to be used like that?

Code snippet that reproduces the problem

https://phpstan.org/r/8b1afd86-ab90-47d1-b17b-530586f8edf7

Expected output

No error found since the interface signature matches how the code is being used.