[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              |   Keywords:
  Focuses:                      |
--------------------------------+-----------------------------
 ==== Documented Behavior

 WordPress documentation states that:

 - `add_metadata()` returns `int|false` — the new meta ID or false on
 failure.
 - `update_metadata()` returns `int|bool` — a new meta ID, true on update,
 or false on failure/no change.

 ==== Actual Behavior

 However, both functions can be short‑circuited via their respective filter
 hooks (`add_{$meta_type}_metadata`, `update_{$meta_type}_metadata`) by
 returning any non‑null value. That value is cast to a boolean value before
 returning it by `update_metadata()` and returned directly by
 `add_metadata()`, possibly violating the documented return type and
 causing unexpected behaviors.

 Specifically:

 - If a filter hooked to `add_{$meta_type}_metadata` returns a non‑null
 value (also non‑boolean types including positive integers suggesting
 success), `add_metadata()` returns that value—even if the metadata was
 never added.

 - If a filter hooked to `update_{$meta_type}_metadata` returns a non‑null
 value, `update_metadata()` casts it to `bool` and returns it—potentially
 returning `true` when no update occurred.

 These behaviors do not align with the documented behaviors and introduce
 ambiguous and misleading return values.

 ==== Proposed Fix

 In add_metadata(), change:

 {{{#!php
 <?php
 if ( null !== $check ) {
     return $check;
 }
 }}}


 to:

 {{{#!php
 <?php
 if ( null !== $check ) {
     return false;
 }
 }}}


 This ensures short‑circuiting always indicates failure and matches the
 documented return type.

 In `update_metadata()`, similarly replace:

 {{{#!php
 <?php
 if ( null !== $check ) {
     return (bool) $check;
 }
 }}}

 with:

 {{{#!php
 <?php
 if ( null !== $check ) {
     return false;
 }
 }}}

 This avoids returning `true` in scenarios where metadata wasn't updated.

 These changes ensure reliable, semantically clear return behavior that
 aligns with documentation and expected usage.

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