Commit Graph

39 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
Peter Wilson 3c6cad73b2 Widgets: Store default options for uninitialized widgets.
Prevent unnecessary database queries on page load by initializing widget options. On sites with uninitialized widgets, this prevents one or two database queries per uninitialized widget on each page load.

Props Chouby, mvraghavan, costdev, peterwilsoncc, spacedmonkey, mukesh27.
Fixes #54677.

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


git-svn-id: http://core.svn.wordpress.org/trunk@53671 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2022-09-09 02:19:10 +00:00
hellofromTonya df4834caea Widgets: Use `isset()` in `WP_Widget:: display_callback()` to support `ArrayIterator` and `ArrayObject`.
[33696] introduced support returning `ArrayIterator` and `ArrayObject` objects from `WP_Widget::get_settings()`. 

Per the PHP manual, `array_key_exists()` stopped supporting this in PHP 8.0.0 and deprecated in PHP 7.4.0.

>For backward compatibility reasons, array_key_exists() will also return true if key is a property defined within an object given as array. This behaviour is deprecated as of PHP 7.4.0, and removed as of PHP 8.0.0.

This commit uses `isset()` instead of `array_key_exists()` which is supported on all current versions of PHP.

Includes unit tests.

Ref:
* https://www.php.net/manual/en/function.array-key-exists.php#refsect1-function.array-key-exists-notes

Follow-up to [32602], [33696].

Props dlh, hellofromTonya, jrf, sergeybiryukov.
Fixes #52728.
Built from https://develop.svn.wordpress.org/trunk@52173


git-svn-id: http://core.svn.wordpress.org/trunk@51765 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2021-11-16 01:43:00 +00:00
Sergey Biryukov 4e2a6681a0 Coding Standards: Simplify the logic in `WP_Widget::get_field_name()` and `::get_field_id()`.
Includes minor code layout fixes for better readability.

Follow-up to [41292], [50953], [50961].

Props 5ubliminal, solarissmoke, tamlyn, jdgrimes, jorbin, stevenkword, drebbits.web, westonruter, jipmoors, justinahinon, helen, lukecarbis, Mte90, hellofromTonya, SergeyBiryukov.
See #16773, #52627.
Built from https://develop.svn.wordpress.org/trunk@51070


git-svn-id: http://core.svn.wordpress.org/trunk@50679 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2021-06-04 10:47:58 +00:00
Sergey Biryukov aabce962ae Widgets: Make sure `WP_Widget` constructor creates a correct `classname` value for a namespaced widget class.
This reverts the changes to `id_base` from [50953] due to backward compatibility concerns, and instead focuses on the `id` and `class` attributes specifically.

With this change, any backslashes in the `id` or `class` attributes for a namespaced widget class are converted to underscores, making it easier to style the output or target the widget with JavaScript.

Follow-up to [50953].

Fixes #44098.
Built from https://develop.svn.wordpress.org/trunk@50961


git-svn-id: http://core.svn.wordpress.org/trunk@50570 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2021-05-24 09:51:56 +00:00
Sergey Biryukov 7670b7dca8 Widgets: Make sure `WP_Widget` constructor creates a correct `id_base` value for a namespaced widget class.
The `id_base` value is used for the widget's `id` and `class` attributes and also for the option name which stores the widget settings (unless the widget specifies a custom `option_name` value).

With this change, any backslashes in the `id_base` for a namespaced widget class are converted to hyphens, making it easier to style the output or target the widget with JavaScript.

This also avoids a `preg_match(): Compilation failed` PHP warning from `next_widget_id_number()` on the Widgets screen, previously caused by unescaped backslashes.

Props Mte90, hermpheus, rogerlos, welcher, SergeyBiryukov.
Fixes #44098.
Built from https://develop.svn.wordpress.org/trunk@50953


git-svn-id: http://core.svn.wordpress.org/trunk@50562 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2021-05-23 08:51:58 +00:00
John Blackbourn 6f3a940e64 Plugins: Replace usage of `$this` in action and filter parameter docblocks with more appropriate variable names.
See #51800, #52217

Fixes #52243

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


git-svn-id: http://core.svn.wordpress.org/trunk@49645 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2021-01-08 14:30:14 +00:00
John Blackbourn 905460bd5e Docs: Standardise the type name for booleans and integers.
This brings these docs inline with the documentation standards.

Props ravipatel, justinahinon

Fixes #51426

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


git-svn-id: http://core.svn.wordpress.org/trunk@48882 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-10-10 20:02:05 +00:00
Sergey Biryukov 91bcefd456 Docs: Add missing description for `wp_convert_widget_settings()` parameters.
Props stevenlinx.
Fixes #50738.
Built from https://develop.svn.wordpress.org/trunk@48580


git-svn-id: http://core.svn.wordpress.org/trunk@48342 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-07-23 13:50:02 +00:00
Sergey Biryukov f5d5b76f6e Docs: Fix typo in `WP_Widget::__construct()` and `::WP_Widget()` DocBlocks.
Props SUM1.
Fixes #50348.
Built from https://develop.svn.wordpress.org/trunk@47936


git-svn-id: http://core.svn.wordpress.org/trunk@47709 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-06-09 15:37:10 +00:00
Sergey Biryukov 001ffe81fb Docs: Improve inline comments per the documentation standards.
Includes minor code layout fixes for better readability.

See #48303.
Built from https://develop.svn.wordpress.org/trunk@47122


git-svn-id: http://core.svn.wordpress.org/trunk@46922 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-01-29 00:45:18 +00:00
Sergey Biryukov 418db0297e Docs: Correct spelling of "subclass" and "overridden" in various docblocks and error messages.
Props garrett-eclipse.
Fixes #48676.
Built from https://develop.svn.wordpress.org/trunk@46739


git-svn-id: http://core.svn.wordpress.org/trunk@46539 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2019-11-17 07:43:01 +00:00
Sergey Biryukov 6be425959a Docs: Add missing `@deprecated` tags to PHP 4 constructors in `WP_Widget` and `WP_Widget_Factory()`.
Correct version number in `_deprecated_constructor()` call in `WP_Widget_Factory()`, see [32990].

Props jrf.
See #48252.
Built from https://develop.svn.wordpress.org/trunk@46627


git-svn-id: http://core.svn.wordpress.org/trunk@46427 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2019-11-02 20:06:03 +00:00
Gary Pendergast 4803fc405e Coding Standards: Fix the `Squiz.PHP.DisallowMultipleAssignments` violations in `wp-includes`.
See #47632.


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


git-svn-id: http://core.svn.wordpress.org/trunk@45401 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2019-07-02 23:42:58 +00:00
Gary Pendergast 56c162fbc9 Coding Standards: Upgrade WPCS to 1.0.0
WPCS 1.0.0 includes a bunch of new auto-fixers, which drops the number of coding standards issues across WordPress significantly. Prior to running the auto-fixers, there were 15,312 issues detected. With this commit, we now drop to 4,769 issues.

This change includes three notable additions:
- Multiline function calls must now put each parameter on a new line.
- Auto-formatting files is now part of the `grunt precommit` script. 
- Auto-fixable coding standards issues will now cause Travis failures.

Fixes #44600.


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


git-svn-id: http://core.svn.wordpress.org/trunk@43400 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2018-08-17 01:51:36 +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
John Blackbourn 4a16295dc5 Docs: Standardise the format used for documenting parameters passed by reference.
See #35974, #41017

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


git-svn-id: http://core.svn.wordpress.org/trunk@41522 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-10-02 22:14:46 +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 5f4497f0af Docs: Fix multiple trivial typos throughout a variety of core files.
Props ottok.
Fixes #38489.

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


git-svn-id: http://core.svn.wordpress.org/trunk@38993 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-10-31 06:28:32 +00:00
Scott Taylor 1119536085 Widgets: `$option_name` and `$alt_option_name` have been used as members ever since `WP_Widget` became an object in 2.8, but never declared.
See #37771.

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


git-svn-id: http://core.svn.wordpress.org/trunk@38259 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-08-22 21:51:28 +00:00
Dominik Schilling cb02b1f1e0 Widgets: Revert [37425] and [37427].
The change can cause fatal errors under certain conditions, like when the subclass has a different function signature for `widget()` or doesn't even implement the method.

See #35981.
Built from https://develop.svn.wordpress.org/trunk@37648


git-svn-id: http://core.svn.wordpress.org/trunk@37614 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-06-06 21:51:28 +00:00
Drew Jaynes 602b51a209 Docs: Standardize filter docs in core classes in wp-includes/* to use third-person singular verbs per the inline documentation standards for PHP.
See #36913.

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


git-svn-id: http://core.svn.wordpress.org/trunk@37460 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-05-22 18:15:28 +00:00
Dominik Schilling 97fc82a879 Widgets: Make `WP_Widget` a real abstract class.
This removes the `die()` call from `WP_Widget::widget()` and converts it to an abstract method.
`WP_Widgets` (later renamed to `WP_Widget`) was introduced in [10764] where the minimum PHP requirement was 4.3, thus no `abstract` was available.

Props johnbillion.
Fixes #35981.
Built from https://develop.svn.wordpress.org/trunk@37425


git-svn-id: http://core.svn.wordpress.org/trunk@37391 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-05-12 20:23:28 +00:00
Drew Jaynes 6683100d2c Docs: Improve the class DocBlock for `WP_Widget` to clarify which methods "should" vs "must" be overridden by extending sub-classes.
Props Frank-Klein.
Fixes #36703.

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


git-svn-id: http://core.svn.wordpress.org/trunk@37309 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-05-02 04:53:27 +00:00
Drew Jaynes c5a5c7c9d1 Docs: Improve inline documentation syntax throughout `WP_Widget`.
Fixes #36298.

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


git-svn-id: http://core.svn.wordpress.org/trunk@37032 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-03-23 05:32:27 +00:00
Drew Jaynes 893871a5d1 Docs: Add missing information to the `WP_Widget` PHP4 constructor DocBlock.
Also add several missing at `@access` tags to other method DocBlocks and clarify parameter docs for `WP_Widget::form_callback()`.

Props raimy.
See #36298.

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


git-svn-id: http://core.svn.wordpress.org/trunk@37031 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-03-23 05:10:26 +00:00
Weston Ruter f3f84d2f21 Customize: Require opt-in for selective refresh of widgets.
* Introduces `customize-selective-refresh-widgets` theme support feature and adds to themes.
* Introduces `customize_selective_refresh` arg for `WP_Widget::$widget_options` and adds to all core widgets.
* Remove `selective_refresh` from being a component that can be removed via `customize_loaded_components` filter.
* Add `WP_Customize_Widgets::get_selective_refreshable_widgets()` and `WP_Customize_Widgets::is_widget_selective_refreshable()`.
* Fix default `selector` for `Partial` instances.
* Implement and improve Masronry sidebar refresh logic in Twenty Thirteen and Twenty Fourteen, including preservation of initial widget position after refresh.
* Re-initialize ME.js when refreshing `Twenty_Fourteen_Ephemera_Widget`.

See #27355.
Fixes #35855.

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


git-svn-id: http://core.svn.wordpress.org/trunk@37007 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-03-21 21:59:29 +00:00
Dominik Schilling 9e73dea03a Introduce a `$parent_class` parameter for `_deprecated_constructor()`.
Use the parameter for the deprecated constructor warning in `WP_Widget` to provide an indication to which widget is using the PHP4 style constructor.

Props sebastian.pisula.
Fixes #33440.
Built from https://develop.svn.wordpress.org/trunk@36541


git-svn-id: http://core.svn.wordpress.org/trunk@36508 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2016-02-16 23:20:26 +00:00
Drew Jaynes 4ced4fce3a Docs: Add missing summaries and `@since` versions to DocBlocks for the `_get_display_callback()`, `_get_update_callback()`, and `_get_form_callback()` methods in `WP_Widget`.
Introduced in [10764].

See #32246.

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


git-svn-id: http://core.svn.wordpress.org/trunk@35919 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-12-16 05:39:25 +00:00
Scott Taylor e7c2544a89 Widgets: when getting settings, and none exist, set them to empty to avoid extraneous database queries on subsequent requests.
Adds unit tests.

Props kovshenin, MikeHansenMe, dlh.
Fixes #26876.

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


git-svn-id: http://core.svn.wordpress.org/trunk@35065 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-10-13 01:13:24 +00:00
Drew Jaynes 6f7a298c18 Docs: Fix the placement and ordering of some `@since` tags following [34780].
See #12133. See #32246.

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


git-svn-id: http://core.svn.wordpress.org/trunk@34747 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-10-02 20:50:25 +00:00
John Blackbourn 7707dbf862 Introduce support for array format field names in `WP_Widget::get_field_name()` and `WP_Widget::get_field_id()`.
Fixes #12133
Props ch1902, welcher

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


git-svn-id: http://core.svn.wordpress.org/trunk@34745 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-10-02 20:24:24 +00:00
Drew Jaynes 66242cbc98 Docs: Improve the method docs for the `widget()`, `update()`, `form()`, and `__construct()` methods in the `WP_Widget` base class.
See #34013. See #32246.

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


git-svn-id: http://core.svn.wordpress.org/trunk@34524 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-09-25 20:31:24 +00:00
Drew Jaynes 783876bd1a Docs: The Widget API is singular.
See #33701.

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


git-svn-id: http://core.svn.wordpress.org/trunk@34356 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-09-22 12:28:27 +00:00
Drew Jaynes a92dc6aeed Docs: Improve the file header for class-wp-widget.php to describe what the file contains.
Also rewrites the class DocBlock summary for `WP_Widget` to better describe the '''purpose''' of the class.

See #33413. See #33701.

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


git-svn-id: http://core.svn.wordpress.org/trunk@33837 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-09-03 02:50:21 +00:00
Drew Jaynes 4d006fad9e Docs: Bring the file header and class DocBlock summaries for class-wp-widget.php in-line with the intention of the docs standard:
* File headers: _What_ the file is
* Class DocBlocks: What purpose the class serves. Mentioning the class name in the class DocBlock is redundant

See #33413

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


git-svn-id: http://core.svn.wordpress.org/trunk@33784 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-08-30 23:14:21 +00:00
Drew Jaynes 2aa0a42661 Docs: Add a file header to wp-includes/class-wp-widget.php, created when the `WP_Widget` class was moved to its own file in [33746].
It's important for every file in WordPress, regardless of makeup or architecture, to have its own file header, even if the file contains nothing but a class. When parsed, files and classes are mutually exclusive and should be documented with this in mind.

See [33746]. See #33413.

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


git-svn-id: http://core.svn.wordpress.org/trunk@33723 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-08-26 07:45:21 +00:00
Scott Taylor c3565b2cba Widgets: move classes into their own files, `widgets.php` loads the new files, so this is 100% BC if someone is loading `widgets.php` directly. New files created using `svn cp`.
Creates: 
`class-wp-widget.php` 
`class-wp-widget-factory.php` 
`widget-functions.php` 

`widgets.php` contains only top-level code. Class files only contain classes. Functions file only contains functions.

See #33413.

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


git-svn-id: http://core.svn.wordpress.org/trunk@33714 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2015-08-26 02:40:23 +00:00