[wp-trac] [WordPress Trac] #63797: Unexpected short‑circuit return values from add_metadata() and update_metadata()

[WordPress Trac]

#63797: Unexpected short‑circuit return values from add_metadata() and
update_metadata()
--------------------------------+------------------------------
 Reporter:  marian1             |       Owner:  (none)
     Type:  defect (bug)        |      Status:  new
 Priority:  normal              |   Milestone:  Awaiting Review
Component:  Options, Meta APIs  |     Version:
 Severity:  normal              |  Resolution:
 Keywords:                      |     Focuses:
--------------------------------+------------------------------

Comment (by marian1):

 I agree, filters are powerful. Perhaps this issue can be addressed in the
 next major release. Third-party code should not be permitted to alter the
 return type of core functions, and ideally should not be permitted to
 change the semantic meaning of returned values.

 In the meantime, it might be worthwhile to reconsider the documentation.
 At present, the function descriptions give the impression that the
 returned values always have clear semantic meaning. However, if the
 function is short-circuited, this is not necessarily the case.

 It is also worth noting that the filter documentation for
 `add_{$meta_type}_metadata` states, "Returning a non-null value will
 effectively short-circuit the function." This could encourage the use of
 non-boolean return values. Additionally, the documented `@param null|bool
 $check` contradicts the intended return values of `add_metadata()` by
 allowing `true`. And, the phrase "Whether to allow adding metadata for the
 given type." is misleading because `true` is then most likely read as
 "Yes, allow adding metadata for the given type" when true effectively
 short-circuits the function.

 The additional information in the documentation of the
 [https://developer.wordpress.org/reference/hooks/update_meta_type_metadata
 /#more-information update_{$meta_type}_metadata hook] states "The filter
 must return a `null` value (the value of `$check`) if the data is be saved
 to the database. If it returns anything else, the `update_metadata`
 function (and therefore the `update_{$meta_type}_metadata` filter) will
 return what the filter callbacks return." which is incorrect,
 `update_metadata` returns `bool` for non null values. However, it is an
 accurate description of the `add_{$meta_type}_metadata` hook that lacks
 such additional information.

 All of this, applies to the meta type specific wrapper functions of
 `add_metadata()` and `update_metadata()` as well.

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