Make WordPress Core

Opened 7 years ago

Closed 9 months ago

Last modified 9 months ago

#41125 closed enhancement (fixed)

Add new `_deprecated_class()` function

Reported by: jrf's profile jrf Owned by: drewapicture's profile DrewAPicture
Milestone: 6.4 Priority: normal
Severity: normal Version: 3.1
Component: General Keywords: has-patch
Focuses: Cc:

Description

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.

Attachments (5)

0001-Add-new-_deprecated_class-function.patch (3.2 KB) - added by jrf 7 years ago.
Patch to add the proposed _deprecated_class() function
0002-Implement-usage-of-the-new-_deprecated_class-functio.patch (1.2 KB) - added by jrf 7 years ago.
Patch to start using the new function in the one instance it is needed ATM
0002-b-Implement-usage-of-the-new-_deprecated_class-functio.patch (1.2 KB) - added by jrf 7 years ago.
Improved version of patch 2 / implementation of the function
41125.diff (2.9 KB) - added by ohryan 9 months ago.
Refresh
41125.2.diff (1.9 KB) - added by wvega 9 months ago.
Adding support for the expectedDeprecated annotation

Download all attachments as: .zip

Change History (13)

@jrf
7 years ago

Patch to add the proposed _deprecated_class() function

@jrf
7 years ago

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

@jrf
7 years ago

Improved version of patch 2 / implementation of the function

This ticket was mentioned in Slack in #core-coding-standards by jrf. View the logs.


7 years ago

#2 @DrewAPicture
7 years ago

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.

#3 @jrf
7 years ago

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

@ohryan
9 months ago

Refresh

@wvega
9 months ago

Adding support for the expectedDeprecated annotation

#4 @DrewAPicture
9 months ago

  • Keywords has-patch added
  • Milestone changed from Awaiting Review to 6.4
  • Owner set to DrewAPicture
  • Status changed from new to reviewing
  • Version changed from 4.9 to 3.1

#5 @DrewAPicture
9 months ago

In 56467:

Introduce a _deprecated_class() function.

Similar to other function in the _deprecated_* series, _deprecated_class() comes with two new hooks: deprecated_class_run and deprecated_class_trigger_error.

Support has also been added for setting class deprecation expectations in tests.

Props jrf, wvega, ohryan.
See #41125.

#6 @DrewAPicture
9 months ago

In 56468:

Fix coding standards for translatable _deprecated_class() message strings

See #41125

#7 @DrewAPicture
9 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 56469:

Properly deprecate both constructors in WP_User_Search.

  • __construct() gets the new _deprecated_class() function
  • WP_User_Search PHP4 style constructor is changed from _deprecated_function() to _deprecated_constructor()

Adds a test to confirm WP_User_Search class is testable as deprecated.

Props jrf, DrewAPicture.
Fixes #41125.

#8 @DrewAPicture
9 months ago

In 56470:

Fix coding standards for Tests_Admin_wpUserSearch

See #41125.

Note: See TracTickets for help on using tickets.