Assuming you’re using versioning, you should make a note of breaking changes in the changelog when it occurs, and announce the breaking change a version ahead of time (or a couple versions ahead of time depending on how widely your project is used). If all you’re doing is expanding an existing function signature and can get away with having the new parameters being optional then you don’t need to announce this, but might still want to consider putting it in the changelog.

To put it plainly, function signatures can’t be deprecated in PHP. You can deprecate an entire function, but not a signature, since PHP functions only have one signature.

Perhaps keep the old method and have the new signature in a function with a transitional name, like “foo()” and “_future_foo()” and wait for the next-next version to replace the old one with the new one. This might complicate things, so it would be best to do what the PHP devs do and just announce the breaking change a version (or two) ahead of time.

If you find yourself changing a function signature and its return type completely, consider instead making a new function and leaving the old one alone, but mark the old one as deprecated. For that, yes, you would use @deprecated

Depreacated does not meen you have a solution yet.

In Java hide() and show() are deprecated since years. The documentation force us to use setVisible(boolean) instead while hide() and show() – anyway hide() and show() are still working good.

@deprecated does not throw a exception, its a warning for developers.

Whenever a method do not exists anymore: a Java-Unittest will fail – but this test must has been written by the people who use your mini-framework.

Also to give info about backward-compatibility: java has a @version-annotation.