[wp-trac] [WordPress Trac] #35574: Add REST API JSON schema information to WP_Widget

[WordPress Trac]

#35574: Add REST API JSON schema information to WP_Widget
------------------------------------------+-----------------------------
 Reporter:  westonruter                   |       Owner:
     Type:  enhancement                   |      Status:  new
 Priority:  normal                        |   Milestone:  Future Release
Component:  Widgets                       |     Version:  2.8
 Severity:  normal                        |  Resolution:
 Keywords:  needs-patch needs-unit-tests  |     Focuses:
------------------------------------------+-----------------------------
Description changed by westonruter:

Old description:

> Widgets often have duplicated logic between the `WP_Widget::widget()`,
> `WP_Widget::update()`, and `WP_Widget::form()` methods for checking if a
> given `$instance` property has been set, and if not, supplying a default
> value. In some cases, these `isset` checks are ''not'' performed
> resulting in PHP notices if the methods are programmatically invoked with
> an empty array. I suggest that we introduce a
> `WP_Widget::$default_instance` property or
> `WP_Widget::get_default_instance()` method that will return the
> `$instance` defaults that can be merged on top of with the current
> `$instance`.
>
> With the REST API, there is an emerging-established way in WordPress for
> describing a data structure, such as a widget instance. One aspect of the
> REST API endpoint schema is the `default` values for given fields on a
> property.
>
> Widgets in WordPress are assumed to be arrays, with the applied filters
> and function return values. With a schema defined, the data type of a
> widget instance would be guaranteed. Meta in the REST API is a challenge
> given that it may or may not contain serialized PHP. Widgets are stored
> in serialized PHP arrays in WP options (though it is possible to store
> them in posts, per #32474). Additionally, the instance arrays may also
> contain PHP objects for classes that cannot be cleanly serialized into
> JSON, and having a REST API JSON schema defined for a widget would
> guarantee that a widget instance can be represented in JSON. This would,
> in turn, allow widgets to be exposed as [https://github.com/WP-API/WP-
> API/issues/19 endpoints] in the REST API, and it would allow widget
> instances to be completely manipulated with JavaScript (such as in the
> Customizer, as described in #33507).
>
> By adding schema information to `WP_Widget`, we get a lot more than
> having default `$instance` data available. For one, the widget form can
> be automatically generated based on the schema if one is not defined
> (i.e. if `noform` is returned from the `WP_Widget::form()` method). (This
> may actually be focus of the Fields API.)

New description:

 With the REST API, there is an emerging-established way in WordPress for
 describing a data structure, such as a widget instance.

 One aspect of the REST API endpoint schema is the `default` values for
 given fields on a property. Widgets often have duplicated logic between
 the `WP_Widget::widget()`, `WP_Widget::update()`, and `WP_Widget::form()`
 methods for checking if a given `$instance` property has been set, and if
 not, supplying a default value. In some cases, these `isset` checks are
 ''not'' performed resulting in PHP notices if the methods are
 programmatically invoked with an empty array. With JSON Schema defined, we
 would provide `$instance` defaults upon which the current stored
 `$instance` can be merged.

 Widgets in WordPress are assumed to be arrays, with the applied filters
 and function return values. With a schema defined, the data type of a
 widget instance would be guaranteed. Meta in the REST API is a challenge
 given that it may or may not contain serialized PHP. Widgets are stored in
 serialized PHP arrays in WP options (though it is possible to store them
 in posts, per #32474). Additionally, the instance arrays may also contain
 PHP objects for classes that cannot be cleanly serialized into JSON, and
 having a REST API JSON schema defined for a widget would guarantee that a
 widget instance can be represented in JSON. This would, in turn, allow
 widgets to be exposed as [https://github.com/WP-API/WP-API/issues/19
 endpoints] in the REST API, and it would allow widget instances to be
 completely manipulated with JavaScript (such as in the Customizer, as
 described in #33507).

 By adding schema information to `WP_Widget`, we get a lot more than having
 default `$instance` data available. For one, the widget form can be
 automatically generated based on the schema if one is not defined (i.e. if
 `noform` is returned from the `WP_Widget::form()` method). (This may
 actually be focus of the Fields API.)

--

--
Ticket URL: <https://core.trac.wordpress.org/ticket/35574#comment:8>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform