WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: Improve documentation for various metadata functions. 

This adds a more specific description for accepted object types: `post`, `comment`, `term`, `user`, or any other object type with an associated meta table.

Props sheparddw, kraftbj, DrewAPicture, SergeyBiryukov.
Fixes #45464.
Built from https://develop.svn.wordpress.org/trunk@47390


git-svn-id: http://core.svn.wordpress.org/trunk@47177 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2020-02-28 12:14:08 +00:00
parent 32be7d6460
commit eb524c0b38
2 changed files with 140 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

262
wp-includes/meta.php
View File

@ -11,20 +11,20 @@
*/ */
/** /**
* Add metadata for the specified object. * Adds metadata for the specified object.
* *
* @since 2.9.0 * @since 2.9.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $object_id ID of the object metadata is for * or any other object type with an associated meta table.
* @param string $meta_key Metadata key * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Optional, default is false. * @param bool $unique Optional. Whether the specified metadata key should be unique for the object.
* Whether the specified metadata key should be unique for the object.
* If true, and the object already has a value for the specified metadata key, * If true, and the object already has a value for the specified metadata key,
* no change will be made. * no change will be made. Default false.
* @return int|false The meta ID on success, false on failure. * @return int|false The meta ID on success, false on failure.
*/ */
function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = false ) { function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = false ) {
@ -63,11 +63,10 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
* @since 3.1.0 * @since 3.1.0
* *
* @param null|bool $check Whether to allow adding metadata for the given type. * @param null|bool $check Whether to allow adding metadata for the given type.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Meta value. Must be serializable if non-scalar. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Whether the specified meta key should be unique * @param bool $unique Whether the specified meta key should be unique for the object.
* for the object. Optional. Default false.
*/ */
$check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique ); $check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
if ( null !== $check ) { if ( null !== $check ) {
@ -95,9 +94,9 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
* *
* @since 3.1.0 * @since 3.1.0
* *
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $_meta_value Meta value. * @param mixed $_meta_value Metadata value. Serialized if non-scalar.
*/ */
do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value ); do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );
@ -127,9 +126,9 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
* @since 2.9.0 * @since 2.9.0
* *
* @param int $mid The meta ID after successful update. * @param int $mid The meta ID after successful update.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $_meta_value Meta value. * @param mixed $_meta_value Metadata value. Serialized if non-scalar.
*/ */
do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value ); do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
@ -137,19 +136,20 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
} }
/** /**
* Update metadata for the specified object. If no value already exists for the specified object * Updates metadata for the specified object. If no value already exists for the specified object
* ID and metadata key, the metadata will be added. * ID and metadata key, the metadata will be added.
* *
* @since 2.9.0 * @since 2.9.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $object_id ID of the object metadata is for * or any other object type with an associated meta table.
* @param string $meta_key Metadata key * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. If specified, only update existing metadata entries with * @param mixed $prev_value Optional. If specified, only update existing metadata entries
* the specified value. Otherwise, update all entries. * with this value. Otherwise, update all entries.
* @return int|bool The new meta field ID if a field with the given key didn't exist and was * @return int|bool The new meta field ID if a field with the given key didn't exist and was
* therefore added, true on successful update, false on failure. * therefore added, true on successful update, false on failure.
*/ */
@ -192,12 +192,11 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_
* @since 3.1.0 * @since 3.1.0
* *
* @param null|bool $check Whether to allow updating metadata for the given type. * @param null|bool $check Whether to allow updating metadata for the given type.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Meta value. Must be serializable if non-scalar. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. If specified, only update existing * @param mixed $prev_value Optional. If specified, only update existing metadata entries
* metadata entries with the specified value. * with this value. Otherwise, update all entries.
* Otherwise, update all entries.
*/ */
$check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value ); $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );
if ( null !== $check ) { if ( null !== $check ) {
@ -243,9 +242,9 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_
* @since 2.9.0 * @since 2.9.0
* *
* @param int $meta_id ID of the metadata entry to update. * @param int $meta_id ID of the metadata entry to update.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $_meta_value Meta value. * @param mixed $_meta_value Metadata value. Serialized if non-scalar.
*/ */
do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value ); do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
@ -257,9 +256,9 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_
* *
* @param int $meta_id ID of metadata entry to update. * @param int $meta_id ID of metadata entry to update.
* @param int $object_id Post ID. * @param int $object_id Post ID.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Meta value. This will be a PHP-serialized string representation of the value if * @param mixed $meta_value Metadata value. This will be a PHP-serialized string representation of the value
* the value is an array, an object, or itself a PHP-serialized string. * if the value is an array, an object, or itself a PHP-serialized string.
*/ */
do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value ); do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
} }
@ -282,9 +281,9 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_
* @since 2.9.0 * @since 2.9.0
* *
* @param int $meta_id ID of updated metadata entry. * @param int $meta_id ID of updated metadata entry.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $_meta_value Meta value. * @param mixed $_meta_value Metadata value. Serialized if non-scalar.
*/ */
do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value ); do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
@ -296,9 +295,9 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_
* *
* @param int $meta_id ID of updated metadata entry. * @param int $meta_id ID of updated metadata entry.
* @param int $object_id Post ID. * @param int $object_id Post ID.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Meta value. This will be a PHP-serialized string representation of the value if * @param mixed $meta_value Metadata value. This will be a PHP-serialized string representation of the value
* the value is an array, an object, or itself a PHP-serialized string. * if the value is an array, an object, or itself a PHP-serialized string.
*/ */
do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value ); do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
} }
@ -308,23 +307,25 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_
} }
/** /**
* Delete metadata for the specified object. * Deletes metadata for the specified object.
* *
* @since 2.9.0 * @since 2.9.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $object_id ID of the object metadata is for * or any other object type with an associated meta table.
* @param string $meta_key Metadata key * @param int $object_id ID of the object metadata is for.
* @param mixed $meta_value Optional. Metadata value. Must be serializable if non-scalar. If specified, only delete * @param string $meta_key Metadata key.
* metadata entries with this value. Otherwise, delete all entries with the specified meta_key. * @param mixed $meta_value Optional. Metadata value. Must be serializable if non-scalar.
* Pass `null`, `false`, or an empty string to skip this check. (For backward compatibility, * If specified, only delete metadata entries with this value.
* it is not possible to pass an empty string to delete those entries with an empty string * Otherwise, delete all entries with the specified meta_key.
* for a value.) * Pass `null`, `false`, or an empty string to skip this check.
* @param bool $delete_all Optional, default is false. If true, delete matching metadata entries for all objects, * (For backward compatibility, it is not possible to pass an empty string
* ignoring the specified object_id. Otherwise, only delete matching metadata entries for * to delete those entries with an empty string for a value.)
* the specified object_id. * @param bool $delete_all Optional. If true, delete matching metadata entries for all objects,
* ignoring the specified object_id. Otherwise, only delete
* matching metadata entries for the specified object_id. Default false.
* @return bool True on successful delete, false on failure. * @return bool True on successful delete, false on failure.
*/ */
function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false ) { function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false ) {
@ -360,9 +361,9 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $
* @since 3.1.0 * @since 3.1.0
* *
* @param null|bool $delete Whether to allow metadata deletion of the given type. * @param null|bool $delete Whether to allow metadata deletion of the given type.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Meta value. Must be serializable if non-scalar. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $delete_all Whether to delete the matching metadata entries * @param bool $delete_all Whether to delete the matching metadata entries
* for all objects, ignoring the specified $object_id. * for all objects, ignoring the specified $object_id.
* Default false. * Default false.
@ -407,9 +408,9 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $
* @since 3.1.0 * @since 3.1.0
* *
* @param string[] $meta_ids An array of metadata entry IDs to delete. * @param string[] $meta_ids An array of metadata entry IDs to delete.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $_meta_value Meta value. * @param mixed $_meta_value Metadata value. Serialized if non-scalar.
*/ */
do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value ); do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
@ -450,9 +451,9 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $
* @since 2.9.0 * @since 2.9.0
* *
* @param string[] $meta_ids An array of metadata entry IDs to delete. * @param string[] $meta_ids An array of metadata entry IDs to delete.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $_meta_value Meta value. * @param mixed $_meta_value Metadata value. Serialized if non-scalar.
*/ */
do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value ); do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
@ -472,17 +473,17 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $
} }
/** /**
* Retrieve metadata for the specified object. * Retrieves metadata for the specified object.
* *
* @since 2.9.0 * @since 2.9.0
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $object_id ID of the object metadata is for * or any other object type with an associated meta table.
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for * @param string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for
* the specified object. * the specified object. Default empty.
* @param bool $single Optional, default is false. * @param bool $single Optional. If true, return only the first value of the specified meta_key.
* If true, return only the first value of the specified meta_key. * This parameter has no effect if meta_key is not specified. Default false.
* This parameter has no effect if meta_key is not specified.
* @return mixed Single metadata value, or array of values * @return mixed Single metadata value, or array of values
*/ */
function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) { function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
@ -506,8 +507,8 @@ function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false )
* *
* @param null|array|string $value The value get_metadata() should return - a single metadata value, * @param null|array|string $value The value get_metadata() should return - a single metadata value,
* or an array of values. * or an array of values.
* @param int $object_id Object ID. * @param int $object_id ID of the object metadata is for.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param bool $single Whether to return only the first value of the specified $meta_key. * @param bool $single Whether to return only the first value of the specified $meta_key.
*/ */
$check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single ); $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
@ -550,12 +551,13 @@ function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false )
} }
/** /**
* Determine if a meta key is set for a given object * Determines if a meta key is set for a given object.
* *
* @since 3.3.0 * @since 3.3.0
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $object_id ID of the object metadata is for * or any other object type with an associated meta table.
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key. * @param string $meta_key Metadata key.
* @return bool True of the key is set, false if not. * @return bool True of the key is set, false if not.
*/ */
@ -590,14 +592,15 @@ function metadata_exists( $meta_type, $object_id, $meta_key ) {
} }
/** /**
* Get meta data by meta ID * Retrieves metadata by meta ID.
* *
* @since 3.3.0 * @since 3.3.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $meta_id ID for a specific meta row * or any other object type with an associated meta table.
* @param int $meta_id ID for a specific meta row.
* @return object|false Meta object or false. * @return object|false Meta object or false.
*/ */
function get_metadata_by_mid( $meta_type, $meta_id ) { function get_metadata_by_mid( $meta_type, $meta_id ) {
@ -650,16 +653,17 @@ function get_metadata_by_mid( $meta_type, $meta_id ) {
} }
/** /**
* Update meta data by meta ID * Updates metadata by meta ID.
* *
* @since 3.3.0 * @since 3.3.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $meta_id ID for a specific meta row * or any other object type with an associated meta table.
* @param string $meta_value Metadata value * @param int $meta_id ID for a specific meta row.
* @param string $meta_key Optional, you can provide a meta key to update it * @param string $meta_value Metadata value.
* @param string $meta_key Optional. You can provide a meta key to update it. Default false.
* @return bool True on successful update, false on failure. * @return bool True on successful update, false on failure.
*/ */
function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) { function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) {
@ -766,14 +770,15 @@ function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key =
} }
/** /**
* Delete meta data by meta ID * Deletes metadata by meta ID.
* *
* @since 3.3.0 * @since 3.3.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param int $meta_id ID for a specific meta row * or any other object type with an associated meta table.
* @param int $meta_id ID for a specific meta row.
* @return bool True on successful delete, false on failure. * @return bool True on successful delete, false on failure.
*/ */
function delete_metadata_by_mid( $meta_type, $meta_id ) { function delete_metadata_by_mid( $meta_type, $meta_id ) {
@ -871,13 +876,14 @@ function delete_metadata_by_mid( $meta_type, $meta_id ) {
} }
/** /**
* Update the metadata cache for the specified objects. * Updates the metadata cache for the specified objects.
* *
* @since 2.9.0 * @since 2.9.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param string|int[] $object_ids Array or comma delimited list of object IDs to update cache for. * @param string|int[] $object_ids Array or comma delimited list of object IDs to update cache for.
* @return array|false Metadata cache for the specified objects, or false on failure. * @return array|false Metadata cache for the specified objects, or false on failure.
*/ */
@ -1006,13 +1012,14 @@ function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $
} }
/** /**
* Retrieve the name of the metadata table for the specified object type. * Retrieves the name of the metadata table for the specified object type.
* *
* @since 2.9.0 * @since 2.9.0
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $type Type of object to get metadata table for (e.g., comment, post, term, or user). * @param string $type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @return string|false Metadata table name, or false if no metadata table exists * @return string|false Metadata table name, or false if no metadata table exists
*/ */
function _get_meta_table( $type ) { function _get_meta_table( $type ) {
@ -1032,11 +1039,12 @@ function _get_meta_table( $type ) {
* *
* @since 3.1.3 * @since 3.1.3
* *
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param string|null $meta_type Optional. Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Optional. Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table. Default empty.
* @return bool Whether the meta key is considered protected. * @return bool Whether the meta key is considered protected.
*/ */
function is_protected_meta( $meta_key, $meta_type = null ) { function is_protected_meta( $meta_key, $meta_type = '' ) {
$protected = ( '_' == $meta_key[0] ); $protected = ( '_' == $meta_key[0] );
/** /**
@ -1044,24 +1052,25 @@ function is_protected_meta( $meta_key, $meta_type = null ) {
* *
* @since 3.2.0 * @since 3.2.0
* *
* @param bool $protected Whether the key is considered protected. * @param bool $protected Whether the key is considered protected.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param string|null $meta_type Type of object metadata is for (e.g., comment, post, term, or user). * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
*/ */
return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type ); return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
} }
/** /**
* Sanitize meta value. * Sanitizes meta value.
* *
* @since 3.1.3 * @since 3.1.3
* @since 4.9.8 The `$object_subtype` parameter was added. * @since 4.9.8 The `$object_subtype` parameter was added.
* *
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Meta value to sanitize. * @param mixed $meta_value Metadata value to sanitize.
* @param string $object_type Type of object the meta is registered to. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param string $object_subtype Optional. The subtype of the object type. * @param string $object_subtype Optional. The subtype of the object type.
*
* @return mixed Sanitized $meta_value. * @return mixed Sanitized $meta_value.
*/ */
function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype = '' ) { function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype = '' ) {
@ -1076,9 +1085,10 @@ function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype =
* *
* @since 4.9.8 * @since 4.9.8
* *
* @param mixed $meta_value Meta value to sanitize. * @param mixed $meta_value Metadata value to sanitize.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param string $object_type Object type. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param string $object_subtype Object subtype. * @param string $object_subtype Object subtype.
*/ */
return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $meta_value, $meta_key, $object_type, $object_subtype ); return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $meta_value, $meta_key, $object_type, $object_subtype );
@ -1093,9 +1103,10 @@ function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype =
* *
* @since 3.3.0 * @since 3.3.0
* *
* @param mixed $meta_value Meta value to sanitize. * @param mixed $meta_value Metadata value to sanitize.
* @param string $meta_key Meta key. * @param string $meta_key Metadata key.
* @param string $object_type Object type. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
*/ */
return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}", $meta_value, $meta_key, $object_type ); return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}", $meta_value, $meta_key, $object_type );
} }
@ -1117,8 +1128,9 @@ function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype =
* @since 4.9.8 The `$object_subtype` argument was added to the arguments array. * @since 4.9.8 The `$object_subtype` argument was added to the arguments array.
* @since 5.3.0 Valid meta types expanded to include "array" and "object". * @since 5.3.0 Valid meta types expanded to include "array" and "object".
* *
* @param string $object_type Type of object this meta is registered to. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param string $meta_key Meta key to register. * or any other object type with an associated meta table.
* @param string $meta_key Meta key to register.
* @param array $args { * @param array $args {
* Data used to describe the meta key when registered. * Data used to describe the meta key when registered.
* *
@ -1138,10 +1150,9 @@ function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype =
* array with 'schema' or 'prepare_callback' keys instead of a boolean. * array with 'schema' or 'prepare_callback' keys instead of a boolean.
* } * }
* @param string|array $deprecated Deprecated. Use `$args` instead. * @param string|array $deprecated Deprecated. Use `$args` instead.
*
* @return bool True if the meta key was successfully registered in the global array, false if not. * @return bool True if the meta key was successfully registered in the global array, false if not.
* Registering a meta key with distinct sanitize and auth callbacks will fire those * Registering a meta key with distinct sanitize and auth callbacks will fire those callbacks,
* callbacks, but will not add to the global registry. * but will not add to the global registry.
*/ */
function register_meta( $object_type, $meta_key, $args, $deprecated = null ) { function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
global $wp_meta_keys; global $wp_meta_keys;
@ -1186,7 +1197,8 @@ function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
* *
* @param array $args Array of meta registration arguments. * @param array $args Array of meta registration arguments.
* @param array $defaults Array of default arguments. * @param array $defaults Array of default arguments.
* @param string $object_type Object type. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param string $meta_key Meta key. * @param string $meta_key Meta key.
*/ */
$args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key ); $args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key );
@ -1247,10 +1259,10 @@ function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
* @since 4.6.0 * @since 4.6.0
* @since 4.9.8 The `$object_subtype` parameter was added. * @since 4.9.8 The `$object_subtype` parameter was added.
* *
* @param string $object_type The type of object. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param string $meta_key The meta key. * or any other object type with an associated meta table.
* @param string $meta_key Metadata key.
* @param string $object_subtype Optional. The subtype of the object type. * @param string $object_subtype Optional. The subtype of the object type.
*
* @return bool True if the meta key is registered to the object type and, if provided, * @return bool True if the meta key is registered to the object type and, if provided,
* the object subtype. False if not. * the object subtype. False if not.
*/ */
@ -1266,8 +1278,9 @@ function registered_meta_key_exists( $object_type, $meta_key, $object_subtype =
* @since 4.6.0 * @since 4.6.0
* @since 4.9.8 The `$object_subtype` parameter was added. * @since 4.9.8 The `$object_subtype` parameter was added.
* *
* @param string $object_type The type of object. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* @param string $meta_key The meta key. * or any other object type with an associated meta table.
* @param string $meta_key Metadata key.
* @param string $object_subtype Optional. The subtype of the object type. * @param string $object_subtype Optional. The subtype of the object type.
* @return bool True if successful. False if the meta key was not registered. * @return bool True if successful. False if the meta key was not registered.
*/ */
@ -1315,7 +1328,8 @@ function unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) {
* @since 4.6.0 * @since 4.6.0
* @since 4.9.8 The `$object_subtype` parameter was added. * @since 4.9.8 The `$object_subtype` parameter was added.
* *
* @param string $object_type The type of object. Post, comment, user, term. * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param string $object_subtype Optional. The subtype of the object type. * @param string $object_subtype Optional. The subtype of the object type.
* @return string[] List of registered meta keys. * @return string[] List of registered meta keys.
*/ */
@ -1337,7 +1351,8 @@ function get_registered_meta_keys( $object_type, $object_subtype = '' ) {
* *
* @since 4.6.0 * @since 4.6.0
* *
* @param string $object_type Type of object to request metadata for. (e.g. comment, post, term, user) * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param int $object_id ID of the object the metadata is for. * @param int $object_id ID of the object the metadata is for.
* @param string $meta_key Optional. Registered metadata key. If not specified, retrieve all registered * @param string $meta_key Optional. Registered metadata key. If not specified, retrieve all registered
* metadata for the specified object. * metadata for the specified object.
@ -1378,7 +1393,8 @@ function get_registered_metadata( $object_type, $object_id, $meta_key = '' ) {
} }
/** /**
* Filter out `register_meta()` args based on a whitelist. * Filters out `register_meta()` args based on a whitelist.
*
* `register_meta()` args may change over time, so requiring the whitelist * `register_meta()` args may change over time, so requiring the whitelist
* to be explicitly turned off is a warranty seal of sorts. * to be explicitly turned off is a warranty seal of sorts.
* *
@ -1387,7 +1403,6 @@ function get_registered_metadata( $object_type, $object_id, $meta_key = '' ) {
* *
* @param array $args Arguments from `register_meta()`. * @param array $args Arguments from `register_meta()`.
* @param array $default_args Default arguments for `register_meta()`. * @param array $default_args Default arguments for `register_meta()`.
*
* @return array Filtered arguments. * @return array Filtered arguments.
*/ */
function _wp_register_meta_args_whitelist( $args, $default_args ) { function _wp_register_meta_args_whitelist( $args, $default_args ) {
@ -1399,7 +1414,8 @@ function _wp_register_meta_args_whitelist( $args, $default_args ) {
* *
* @since 4.9.8 * @since 4.9.8
* *
* @param string $object_type Type of object to request metadata for. (e.g. comment, post, term, user) * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param int $object_id ID of the object to retrieve its subtype. * @param int $object_id ID of the object to retrieve its subtype.
* @return string The object subtype or an empty string if unspecified subtype. * @return string The object subtype or an empty string if unspecified subtype.
*/ */

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '5.4-beta3-47389'; $wp_version = '5.4-beta3-47390';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.