Add new `_deprecated_class()` function

[jrf]

Up to now, there is only one class I know of that is completely deprecated (there may be more).

As the newer WP Core code is more and more class based, it is likely that more classes will be deprecated in the future.

With that in mind, I'd like to propose adding a new _deprecated_class() method to be used for classes which have been completely deprecated.
I propose the new function should be used in the constructor and possibly the get_instance() method for those classes set up as a singleton.

The other methods in the class should (continue to) use the _deprecated_function() method.

This way developers using the class will be informed with more accurate and better actionable information.

This will still not inform devs for every single type of usage of a class, but should improve things.

Additionally, the ​WordPress Coding Standards PHPCS ruleset (WPCS) can sniff for nearly all of the other uses and notify those developers who use WPCS of the class deprecation. A new WP.DeprecatedClasses sniff will be added to WPCS to this end.

Some examples of how classes can be used in code:

• $a = new WP_User_Search; - This should throw the new _deprecated_class() error.
• echo \WP_User_Search::prepare_query(); - This should throw the existing _deprecated_function() error.
• $a = new WP_User_Search->query(); - This should throw the new _deprecated_class() as well as the existing _deprecated_function() error.

• class My_User_Search extends WP_User_Search {} - Depending on which methods are used/overloaded, the dev may or may not receive notification about this. WPCS however will detect this & notify the dev.
• echo WP_User_Search::$users_per_page; - The dev will generally not be notified about this, though may receive a static vs non-static PHP notice. WPCS however will detect this as usage of a deprecated class & notify the dev.

• echo $a->users_per_page; - This will go undetected completely, but the user should have received a _deprecated_class() error when $a was being instantiated.

Related to and based on the same investigation as ticket: #41121

Important note about the suggested function implementation as per the attached patch:

The new _deprecated_class() method uses the E_USER_DEPRECATED constant which is only available since PHP 5.3.
Ticket #36561 addresses this and can therefore be considered a blocker for this ticket. Ticket #36561 has been earmarked for 4.9.

[jrf]

Patch to add the proposed _deprecated_class() function

[jrf]

Patch to start using the new function in the one instance it is needed ATM

[jrf]

Improved version of patch 2 / implementation of the function

[DrewAPicture]

Would it not be a bit moot to also deprecate methods when the entire class is already marked deprecated with this new function? I can see it from the Code Reference perspective where a single method has its own page.

[jrf]

Would it not be a bit moot to also deprecate methods when the entire class is already marked deprecated with this new function? I can see it from the Code Reference perspective where a single method has its own page.

@DrewAPicture Sorry, only just noticed the comment here. My reply with an argument as to why we should, is in the related thread: https://core.trac.wordpress.org/ticket/41121#comment:20