[wp-trac] [WordPress Trac] #41125: Add new `_deprecated_class()` function

[WordPress Trac]

#41125: Add new `_deprecated_class()` function
-------------------------+-----------------------------
 Reporter:  jrf          |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  General      |    Version:  trunk
 Severity:  normal       |   Keywords:
  Focuses:               |
-------------------------+-----------------------------
 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 [https://github.com/WordPress-Coding-Standards
 /WordPress-Coding-Standards 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.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/41125>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform