Commit Graph

34 Commits

Author SHA1 Message Date
Sergey Biryukov 77dfc892fe Docs: Document default values for optional parameters in various DocBlocks.
Props paulkevan, costdev, audrasjb, SergeyBiryukov.
See #56792.
Built from https://develop.svn.wordpress.org/trunk@55398


git-svn-id: http://core.svn.wordpress.org/trunk@54931 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2023-02-21 16:39:19 +00:00
Sergey Biryukov c03305852e Code Modernization: Add `AllowDynamicProperties` attribute to all (parent) classes.
Dynamic (non-explicitly declared) properties are deprecated as of PHP 8.2 and are expected to become a fatal error in PHP 9.0.

There are a number of ways to mitigate this:
* If it is an accidental typo for a declared property: fix the typo.
* For known properties: declare them on the class.
* For unknown properties: add the magic `__get()`, `__set()`, et al. methods to the class or let the class extend `stdClass` which has highly optimized versions of these magic methods built in.
* For unknown ''use'' of dynamic properties, the `#[AllowDynamicProperties]` attribute can be added to the class. The attribute will automatically be inherited by child classes.

Trac ticket #56034 is open to investigate and handle the third and fourth type of situations, however it has become clear this will need more time and will not be ready in time for WP 6.1.

To reduce “noise” in the meantime, both in the error logs of WP users moving onto PHP 8.2, in the test run logs of WP itself, in test runs of plugins and themes, as well as to prevent duplicate tickets from being opened for the same issue, this commit adds the `#[AllowDynamicProperties]` attribute to all “parent” classes in WP.

The logic used for this commit is as follows:
* If a class already has the attribute: no action needed.
* If a class does not `extend`: add the attribute.
* If a class does `extend`:
 - If it extends `stdClass`: no action needed (as `stdClass` supports dynamic properties).
 - If it extends a PHP native class: add the attribute.
 - If it extends a class from one of WP's external dependencies: add the attribute.
* In all other cases: no action — the attribute should not be needed as child classes inherit from the parent.

Whether or not a class contains magic methods has not been taken into account, as a review of the currently existing magic methods has shown that those are generally not sturdy enough and often even set dynamic properties (which they should not). See the [https://www.youtube.com/watch?v=vDZWepDQQVE live stream from August 16, 2022] for more details.

This commit only affects classes in the `src` directory of WordPress core.
* Tests should not get this attribute, but should be fixed to not use dynamic properties instead. Patches for this are already being committed under ticket #56033.
* While a number bundled themes (2014, 2019, 2020, 2021) contain classes, they are not a part of this commit and may be updated separately.

Reference: [https://wiki.php.net/rfc/deprecate_dynamic_properties PHP RFC: Deprecate dynamic properties].

Follow-up to [53922].

Props jrf, hellofromTonya, markjaquith, peterwilsoncc, costdev, knutsp, aristath.
See #56513, #56034.
Built from https://develop.svn.wordpress.org/trunk@54133


git-svn-id: http://core.svn.wordpress.org/trunk@53692 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2022-09-12 15:47:14 +00:00
John Blackbourn 6aa053dc01 Docs: Various docblock improvements.
See #54729

Built from https://develop.svn.wordpress.org/trunk@53299


git-svn-id: http://core.svn.wordpress.org/trunk@52888 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2022-04-28 09:46:21 +00:00
John Blackbourn c1401d7009 General: Docblock improvements for the `WP_Error` class.
Props garrett-eclipse

See #38777

Built from https://develop.svn.wordpress.org/trunk@49116


git-svn-id: http://core.svn.wordpress.org/trunk@48878 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-10-09 22:30:04 +00:00
John Blackbourn 543b14ed0a General: Introduce the ability to merge multiple `WP_Error` objects into one another, and to store more than one item of data for an error.
This allows multiple errors to be instantiated independently but collected into one without having to manually combine their properties.

Props rmccue, dlh, TimothyBlynJacobs

Fixes #38777

Built from https://develop.svn.wordpress.org/trunk@49115


git-svn-id: http://core.svn.wordpress.org/trunk@48877 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-10-09 22:22:05 +00:00
John Blackbourn 964d0784be General: Introduce the `wp_error_added` and `wp_error_checked` actions.
These actions allow debugging tools to track `WP_Error` instances as they're created and subsequently passed between functions which check for error objects.

Props Shelob9, Mte90, TimothyBlynJacobs, johnbillion

Fixes #40568


Built from https://develop.svn.wordpress.org/trunk@49022


git-svn-id: http://core.svn.wordpress.org/trunk@48784 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-09-20 17:44:07 +00:00
John Blackbourn 57a3f803ae Docs: First pass at some inline docs fixes mostly made by PHPCBF.
See #49572, #50744
Built from https://develop.svn.wordpress.org/trunk@48586


git-svn-id: http://core.svn.wordpress.org/trunk@48348 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-07-23 20:01:04 +00:00
desrosj cf1e3b0c40 Docs: Update `since` annotations `WP_Error::has_errors()`
Introduced in [42761].

Fixes #42742.
Built from https://develop.svn.wordpress.org/trunk@44527


git-svn-id: http://core.svn.wordpress.org/trunk@44358 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2019-01-09 22:42:51 +00:00
Sergey Biryukov 0e802a627d General: Introduce `WP_Error::has_errors()` method and use it where appropriate.
Props robdxw, DrewAPicture, SergeyBiryukov.
Fixes #42742.
Built from https://develop.svn.wordpress.org/trunk@42761


git-svn-id: http://core.svn.wordpress.org/trunk@42591 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2018-02-27 02:31:31 +00:00
Gary Pendergast aaf99e6913 Code is Poetry.
WordPress' code just... wasn't.
This is now dealt with.

Props jrf, pento, netweb, GaryJ, jdgrimes, westonruter, Greg Sherwood from PHPCS, and everyone who's ever contributed to WPCS and PHPCS.
Fixes #41057.


Built from https://develop.svn.wordpress.org/trunk@42343


git-svn-id: http://core.svn.wordpress.org/trunk@42172 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-11-30 23:11:00 +00:00
Drew Jaynes 0860bb2771 Docs: Remove `@access` notations from method DocBlocks in wp-includes/* classes.
Prior to about 2013, many class methods lacked even access modifiers which made the `@access` notations that much more useful. Now that we've gotten to a point where the codebase is more mature from a maintenance perspective and we can finally remove these notations. Notable exceptions to this change include standalone functions notated as private as well as some classes still considered to represent "private" APIs.

See #41452.

Built from https://develop.svn.wordpress.org/trunk@41162


git-svn-id: http://core.svn.wordpress.org/trunk@41002 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-07-27 00:41:44 +00:00
Drew Jaynes 1d95dcfa2c Docs: Remove superfluous `@package WordPress` and `@subpackage` notations used outside of file headers in a variety of core files.
Per the inline documentation standards for PHP, there should only be one `@package` and/or `@subpackage` notation per file, and only in the file header.

See #41017.

Built from https://develop.svn.wordpress.org/trunk@40988


git-svn-id: http://core.svn.wordpress.org/trunk@40838 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-07-01 16:58:42 +00:00
Scott Taylor 4d17b67eed Load: move `is_wp_error()` to `load.php` so that `WP_Error` is in a file by itself.
See #37827.

Built from https://develop.svn.wordpress.org/trunk@38363


git-svn-id: http://core.svn.wordpress.org/trunk@38304 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-08-26 09:58:28 +00:00
Drew Jaynes f52a8cb1fa Docs: Remove/replace invalid inline `@link` tags in DocBlocks in wp-includes/*.
Fixes #36910.

Built from https://develop.svn.wordpress.org/trunk@37487


git-svn-id: http://core.svn.wordpress.org/trunk@37455 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-05-22 17:39:28 +00:00
Scott Taylor bd8fafea54 Use `void` instead of `null` where appropriate when pipe-delimiting `@return` types. If a `@return` only contains `void`, remove it.
See #32444.

Built from https://develop.svn.wordpress.org/trunk@32568


git-svn-id: http://core.svn.wordpress.org/trunk@32538 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-05-24 05:40:25 +00:00
Scott Taylor fe6b5983df In PHP 5.0.0, `is_a()` became deprecated in favour of the `instanceof` operator. Calling `is_a()` would result in an `E_STRICT` warning.
In PHP 5.3.0, `is_a()` is no longer deprecated, and will therefore no longer throw `E_STRICT` warnings.

To avoid warnings in PHP < 5.3.0, convert all `is_a()` calls to `$var instanceof WP_Class` calls.

`instanceof` does not throw any error if the variable being tested is not an object, it simply returns `false`.

Props markoheijnen, wonderboymusic.
Fixes #25672.

Built from https://develop.svn.wordpress.org/trunk@31188


git-svn-id: http://core.svn.wordpress.org/trunk@31169 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-01-16 01:06:24 +00:00
Scott Taylor d8e5aabab5 In `WP_Error`:
* `wp_send_json_error()` accesses `$errors` on an instance, it must be `public`
* `$error_data` is a local message cache for error codes and doesn't particularly hide info, would be the only non-public field or method in the class

Make `$errors` and `$error_data` public and remove magic methods.

See #30891.

Built from https://develop.svn.wordpress.org/trunk@31138


git-svn-id: http://core.svn.wordpress.org/trunk@31119 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-01-11 00:01:22 +00:00
Scott Taylor 0a511680f4 Adding a `@return` annotation to constructors is generally not recommended as a constructor does not have a meaningful return value. Constructors do not have meaningful return values, anything that is returned from here is discarded.
See #30799.

Built from https://develop.svn.wordpress.org/trunk@31126


git-svn-id: http://core.svn.wordpress.org/trunk@31107 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-01-10 06:54:23 +00:00
Scott Taylor e619abda6e Improve various `@param` docs for `src/wp-includes/*`.
See #30224.

Built from https://develop.svn.wordpress.org/trunk@30681


git-svn-id: http://core.svn.wordpress.org/trunk@30671 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-12-01 01:34:24 +00:00
Konstantin Kovshenin 2b88252b38 New `remove()` method and some unit tests for the `WP_Error` class.
props stephenharris.
fixes #28092.

Built from https://develop.svn.wordpress.org/trunk@29854


git-svn-id: http://core.svn.wordpress.org/trunk@29617 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-10-08 07:12:18 +00:00
Drew Jaynes a8583d5f19 Fix some words that aren't words.
See #28885.

Built from https://develop.svn.wordpress.org/trunk@29454


git-svn-id: http://core.svn.wordpress.org/trunk@29232 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-08-09 19:30:17 +00:00
Drew Jaynes bf3f95f36f Fill out inline documentation for magic methods added to the `WP_Error` class in [28511].
See #27881, #22234 and #28885.

Built from https://develop.svn.wordpress.org/trunk@29144


git-svn-id: http://core.svn.wordpress.org/trunk@28928 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-07-13 23:42:14 +00:00
John Blackbourn 52aa3a5112 Revert [29033] pending further discussion. See #28319.
Built from https://develop.svn.wordpress.org/trunk@29046


git-svn-id: http://core.svn.wordpress.org/trunk@28834 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-07-09 19:19:14 +00:00
John Blackbourn 1e681c1421 Add a `create_wp_error` action which is called when a `WP_Error` instance is created. Fixes #28319. Props ebinnion
Built from https://develop.svn.wordpress.org/trunk@29033


git-svn-id: http://core.svn.wordpress.org/trunk@28821 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-07-08 18:47:15 +00:00
Drew Jaynes 10e48ccbf2 Improve inline documentation for the `__construct()` and `add()` methods in `WP_Error` class.
Props jdgrimes.
Fixes #28203.

Built from https://develop.svn.wordpress.org/trunk@28660


git-svn-id: http://core.svn.wordpress.org/trunk@28478 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-06-04 06:06:14 +00:00
Scott Taylor 85f73cf458 Classes that have `__set()` also need `__isset()` and `__unset()`.
See #27881, #22234.

Built from https://develop.svn.wordpress.org/trunk@28524


git-svn-id: http://core.svn.wordpress.org/trunk@28350 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-05-19 06:52:14 +00:00
Scott Taylor 821246b4ae Some classes with `__get()` method also need `__set()`.
See #27881, #22234.

Built from https://develop.svn.wordpress.org/trunk@28521


git-svn-id: http://core.svn.wordpress.org/trunk@28347 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-05-19 06:31:15 +00:00
Scott Taylor 72d096b007 Add access modifiers to methods/members in `WP_Error`. Add a magic `__get()` method for BC.
See #27881, #22234.

Built from https://develop.svn.wordpress.org/trunk@28511


git-svn-id: http://core.svn.wordpress.org/trunk@28337 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2014-05-19 05:50:14 +00:00
Sergey Biryukov d842da10e7 Correct inline docs for is_wp_error(). props johnbillion. fixes #24637.
git-svn-id: http://core.svn.wordpress.org/trunk@24507 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2013-06-24 18:23:45 +00:00
ryan e3b46b25d3 Lose EOF ?>. Clean up EOF newlines. fixes #12307
git-svn-id: http://svn.automattic.com/wordpress/trunk@19712 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2012-01-08 17:01:11 +00:00
duck_ e4ed63fc6f Fix typos in documentation (wp-includes/[a-h]). See #18560.
git-svn-id: http://svn.automattic.com/wordpress/trunk@18633 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2011-09-03 16:02:41 +00:00
ryan 04487fc268 Constructor cleanup. Props ocean90. fixes #16768
git-svn-id: http://svn.automattic.com/wordpress/trunk@17771 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2011-04-29 20:05:12 +00:00
nacin 04deafb31c File-level phpdoc for new class files. fixes #10287.
git-svn-id: http://svn.automattic.com/wordpress/trunk@16101 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2010-10-30 14:09:05 +00:00
nacin 731bf1fb06 Begin the dissolution of classes.php. see #10287.
git-svn-id: http://svn.automattic.com/wordpress/trunk@16099 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2010-10-30 07:02:06 +00:00