[wp-trac] [WordPress Trac] #38323: Reconsider $object_subtype handling in `register_meta()`

[WordPress Trac]

#38323: Reconsider $object_subtype handling in `register_meta()`
----------------------------------------+-----------------------
 Reporter:  flixos90                    |       Owner:  flixos90
     Type:  enhancement                 |      Status:  assigned
 Priority:  normal                      |   Milestone:  5.0
Component:  Options, Meta APIs          |     Version:
 Severity:  normal                      |  Resolution:
 Keywords:  has-patch needs-unit-tests  |     Focuses:  rest-api
----------------------------------------+-----------------------

Comment (by flixos90):

 [attachment:38323.6.diff] implements the decision (and suggestions) we
 made in the REST API chat on May 3rd. These are the changes compared to
 the previous patch:

 * Meta keys registered for a specific object type and object subtype now
 overrule meta keys only registered for a specific object type. That means:
 If you call `register_meta( 'post', 'mykey', array( ... ) )`, the
 registration data from that call will determine the behavior of the key on
 every post of any post type. However, if you also have `register_meta(
 'post', 'mykey', array( 'object_subtype' => 'post', ... )` somewhere else,
 the registration data from that call will determine the behavior on the
 posts of the 'post' post type, overriding the other, less-specific
 registration. For all other post types, the behavior will still be based
 on the registration data for the entire object type. So registration
 without specifying an object subtype essentially acts as a fallback. That
 specifically means:
     * A new `auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}`
 filter is introduced and called in `map_meta_cap()` for capability checks
 related to metadata. If a function is hooked into that filter, that filter
 will fire. Otherwise, the previously existing, less-specific
 `auth_{$object_type}_meta_{$meta_key}` will fire. To clarify, they are
 exclusive to each other, and ''only one'' of them will fire for the same
 check. This must be clearly highlighted in the dev-note. Since conflicts
 should be rare, most code will continue to work, but it will be
 recommended to switch to registering for a specific subtype.
     * The `auth_{$object_type}_{$object_subtype}_meta_{$meta_key}` filter
 which appears to be an accidental remainder of the original plans from
 #35658 is now deprecated, to reduce the chance for conflicts. The name of
 the new filter is more accurate and prevents weird edge-cases where the
 filter name for an object type "post" and subtype "post" could
 theoretically conflict with the filter name for an object type called
 "post_post" (bad example, but you get the gist).
     * A new
 `sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}` filter is
 introduced in `sanitize_meta()`. Similar to the auth filters, if that
 filter is being used, it will fire, and ''only otherwise'' the previously
 existing, less-specific `sanitize_{$object_type}_meta_{$meta_key}` will
 fire. This as well must be clearly highlighted in the dev-note.
     * The flow of determining the capabilities for metadata capabilities
 in `map_meta_cap()` was adjusted to be easier-readable. First of all the
 default value for a given meta key is determined by calling
 `is_protected_meta()`. Then, it is filtered through either
 `auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}` or
 `auth_{$object_type}_meta_{$meta_key}`. Then, it is further filtered
 through the deprecated
 `auth_{$object_type}_{$object_subtype}_meta_{$meta_key}` (only if still
 being used, which is unlikely due to the relatively short existence of
 this filter). After that, we have the final result whether to allow or
 disallow the action.
     * In the REST API, the behavior of a meta key is based on whether it
 is registered for the current object type and subtype. ''Only if'' there
 is no such registration present, it falls back to a registration for the
 object type without subtype (if available).
 * Easy-to-understand utility functions wrapping around `register_meta()`
 and `unregister_meta_key()` have been introduced, similar like we have
 functions like `get_post_meta()`, `get_term_meta()` etc. The new functions
 are:
     * `register_post_meta( $post_type, $meta_key, $args )`
     * `unregister_post_meta( $post_type, $meta_key )`
     * `register_term_meta( $taxonomy, $meta_key, $args )`
     * `unregister_term_meta( $taxonomy, $meta_key )`
     * `register_comment_meta( $comment_type, $meta_key, $args )`
     * `unregister_comment_meta( $comment_type, $meta_key )`
     * `register_user_meta( $user_type, $meta_key, $args )`
     * `unregister_user_meta( $user_type, $meta_key )`

 We may wanna discuss the signature of these functions. Some explanation on
 my approach here: I put the subtype parameter first, as we wanna encourage
 developers to register their metadata per subtype (i.e. make it a required
 parameter). While comments and users don't really have subtypes at this
 point, I still think we should be consistent in all these functions, and
 by that also keep them future-proof (if we decide to make actual use of
 comment types or introduce user types). Furthermore, in each of the
 functions it is documented that an empty string may be passed as first
 parameter to ignore the subtype and still use the functions for the entire
 object type - so they still allow for full flexibility.

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