Deprecation messages are often not helpful

[nielsdos]

Description

Deprecation messages often just say that something is deprecated, without pointing me to an alternative or a solution, or saying something will be removed.

Examples:

Calling FFI::new() statically is deprecated
Calling FFI::cast() statically is deprecated

Okay, so what should I do instead? I'd look into the migration guide, which I couldn't find easily on php.net, I ended up Googling "PHP 8.3 migration guide" to find it. I find https://www.php.net/manual/en/migration83.deprecated.php but that also doesn't point me to a solution because it just says "Calling FFI::cast(), FFI::new(), and FFI::type() statically is now deprecated.".

I just happen to know that I should use cdef() because I followed the discussions on the mailing list, but otherwise I'd have to Google to find the solution even though the message could've just told me.

Another example:

Creation of dynamic property %s::$%s is deprecated

Well, you still can use dynamic properties (and can't always avoid it) but this message gives the impression you can't anymore. And I've seen people actually be confused about this that it wouldn't be possible anymore. But that's not true because we have an attribute that allows opt-in dynamic properties.

The PDO::FETCH_SERIALIZE mode is deprecated

So, will this be removed or ... ?

The following is an example of a good deprecation message because it points me to what I should do instead:

Calling IntlCalendar::set() with more than 2 arguments is deprecated, use either IntlCalendar::setDate() or IntlCalendar::setDateTime() instead

The point I'm trying to make is that often the deprecation messages are not helpful.
It would be great if we have a policy that says either: if something is going to be removed or if there's an alternative.

[claudepache]

Any RFC proposing to deprecate something should be required to actually spell out the intended deprecation message. Good example: https://wiki.php.net/rfc/deprecate-implicitly-nullable-types#proposal

[cmb69]

For those cases where the information would be too long for the deprecation message (e.g. possibly for the "creation of dynamic property" deprecation), maybe we should point to the documentation – if we can ensure that the URL won't change, and the respective documentation is already available. The latter would be an issue for the documentation proper (since the migration guide etc. is only made available around GA).

[cmb69]

I've changed the status to "verified", but likely this requires the RFC process. :(

[TimWolla]

See also #14750, which added deprecation messages for (almost) all of the functions that are currently deprecated.