Introduce wp_trigger_error() to compliment _doing_it_wrong()

[azaozz]

The _doing_it_wrong() function was introduced 12 years ago (see #15824 and [16939]) for "telling people the code they have written won't work". Since then it has been used quite a bit, currently at around 180 places in core as it is a convenient way to trigger a PHP user error.

However that convenience has resulted in shifting the initial purpose, which was to tell developers they are doing something wrong. Lately _doing_it_wrong() seems to be used in any context, not specifically to "tell off" the developers and get them to fix their code.

In that terms I think it would be good to have a "general use" function that has similar functionality but "milder" messaging. Such function can be used by the current _doing_it_wrong(), and should be enhanced a little to handle the combinations of all PHP debugging constants: WP_DEBUG, WP_DEBUG_DISPLAY, and WP_DEBUG_LOG.

[peterwilsoncc]

Coincidentally, I was discussing this with another contributor recently as a suitable helper function so would very much like to see it.

My preference would be for core to swap all instances of _doing_it_wrong() to use the new function as "you're doing it wrong" is the least helpful way of advising developers how to improve their code.

Unfortunately throwing deprecation notices in _doing_it_wrong() isn't really possible as then WordPress would be throwing notices on it's notices and, ugh, that would be ugly.

[costdev]

@azaozz should be enhanced a little to handle the combinations of all PHP debugging constants: WP_DEBUG, WP_DEBUG_DISPLAY, and WP_DEBUG_LOG.

Interesting! What are your thoughts on how this would behave for the different combinations?