I'm planning to add return types to interface methods in a #PHP library. Because of #BC I plan to do this in a next major release.
What's the best practice to document this return type change now, so the users of the library can add the return types now instead of waiting for the major release? Is there a recommended #phpdoc annotation? Or should I use the ReturnTypeWillChange attribute?
@art4 why would users be adding return types to your library? If you already have the docblock return type, I think you don't need an annotation. You're users can use phpstan or psalm to make sure they are using your returned values in a forward-compatible way
@omerida because the library offers interfaces or abstract classes that the users have implemented/extended.
I'm looking for a programmatically way to inform them about changes they will have to do in their code.
@art4 gotcha. You should look at rector and providing rules that will add the return type hints automatically to implementations. Then again, worst case - won't PHP throw an error when the return type hint is missing or different than the interface/base class?
@omerida
I'm not talking about doing the actual changes, I'm only talking about informing the users about the future work. Not every user is reading the issues or project blog. And yes, at least #PHP will throw exceptions after users upgrades to v2 without making the changes.
But I would like to offer a FC layer so users are informed upfront by their IDE, #PHPStan or other tools as early as possible. The goal is to improve the upgrade path.
Add comment