| [ Index ] |
PHP Cross Reference of WordPress |
[Source view] [Print] [Project Stats]
Core Metadata API Functions for retrieving and manipulating metadata of various WordPress object types. Metadata for an object is a represented by a simple key-value pair. Objects may contain multiple metadata entries that share the same key and differ only in their value.
| File Size: | 1794 lines (63 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
| add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = false ) X-Ref |
| Adds metadata for the specified object. return: int|false The meta ID on success, false on failure. 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. param: string $meta_key Metadata key. param: mixed $meta_value Metadata value. Must be serializable if non-scalar. param: bool $unique Optional. Whether the specified metadata key should be unique for the object. since: 2.9.0 |
| update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) X-Ref |
| Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added. return: int|bool The new meta field ID if a field with the given key didn't exist 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. param: string $meta_key Metadata key. param: mixed $meta_value Metadata value. Must be serializable if non-scalar. param: mixed $prev_value Optional. Previous value to check before updating. since: 2.9.0 |
| delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false ) X-Ref |
| Deletes metadata for the specified object. return: bool True on successful delete, false on failure. 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. param: string $meta_key Metadata key. param: mixed $meta_value Optional. Metadata value. Must be serializable if non-scalar. param: bool $delete_all Optional. If true, delete matching metadata entries for all objects, since: 2.9.0 |
| get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) X-Ref |
| Retrieves the value of a metadata field for the specified object type and ID. If the meta field exists, a single value is returned if `$single` is true, or an array of values if it's false. If the meta field does not exist, the result depends on get_metadata_default(). By default, an empty string is returned if `$single` is true, or an empty array if it's false. return: mixed An array of values if `$single` is false. 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. param: string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for param: bool $single Optional. If true, return only the first value of the specified `$meta_key`. since: 2.9.0 |
| get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = false ) X-Ref |
| Retrieves raw metadata value for the specified object. return: mixed An array of values if `$single` is false. 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. param: string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for param: bool $single Optional. If true, return only the first value of the specified `$meta_key`. since: 5.5.0 |
| get_metadata_default( $meta_type, $object_id, $meta_key, $single = false ) X-Ref |
| Retrieves default metadata value for the specified meta key and object. By default, an empty string is returned if `$single` is true, or an empty array if it's false. return: mixed An array of default values if `$single` is false. 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. param: string $meta_key Metadata key. param: bool $single Optional. If true, return only the first value of the specified `$meta_key`. since: 5.5.0 |
| metadata_exists( $meta_type, $object_id, $meta_key ) X-Ref |
| Determines if a meta field with the given key exists for the given object ID. return: bool Whether a meta field with the given key exists. 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. param: string $meta_key Metadata key. since: 3.3.0 |
| get_metadata_by_mid( $meta_type, $meta_id ) X-Ref |
| Retrieves metadata by meta ID. return: stdClass|false { 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. since: 3.3.0 |
| update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) X-Ref |
| Updates metadata by meta ID. return: bool True on successful update, false on failure. 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. param: string $meta_value Metadata value. Must be serializable if non-scalar. param: string|false $meta_key Optional. You can provide a meta key to update it. Default false. since: 3.3.0 |
| delete_metadata_by_mid( $meta_type, $meta_id ) X-Ref |
| Deletes metadata by meta ID. return: bool True on successful delete, false on failure. 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. since: 3.3.0 |
| update_meta_cache( $meta_type, $object_ids ) X-Ref |
| Updates the metadata cache for the specified objects. return: array|false Metadata cache for the specified objects, or false on failure. param: string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', param: string|int[] $object_ids Array or comma delimited list of object IDs to update cache for. since: 2.9.0 |
| wp_metadata_lazyloader() X-Ref |
| Retrieves the queue for lazy-loading metadata. return: WP_Metadata_Lazyloader Metadata lazyloader queue. since: 4.5.0 |
| get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) X-Ref |
| Given a meta query, generates SQL clauses to be appended to a main query. return: array Associative array of `JOIN` and `WHERE` SQL. param: array $meta_query A meta query. param: string $type Type of meta. param: string $primary_table Primary database table name. param: string $primary_id_column Primary ID column name. param: object $context Optional. The main query object since: 3.2.0 |
| _get_meta_table( $type ) X-Ref |
| Retrieves the name of the metadata table for the specified object type. return: string|false Metadata table name, or false if no metadata table exists param: string $type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', since: 2.9.0 |
| is_protected_meta( $meta_key, $meta_type = '' ) X-Ref |
| Determines whether a meta key is considered protected. return: bool Whether the meta key is considered protected. param: string $meta_key Metadata key. param: string $meta_type Optional. Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', since: 3.1.3 |
| sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype = '' ) X-Ref |
| Sanitizes meta value. return: mixed Sanitized $meta_value. param: string $meta_key Metadata key. param: mixed $meta_value Metadata value to sanitize. param: string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', param: string $object_subtype Optional. The subtype of the object type. since: 3.1.3 since: 4.9.8 The `$object_subtype` parameter was added. |
| register_meta( $object_type, $meta_key, $args, $deprecated = null ) X-Ref |
| Registers a meta key. It is recommended to register meta keys for a specific combination of object type and object subtype. If passing an object subtype is omitted, the meta key will be registered for the entire object type, however it can be partly overridden in case a more specific meta key of the same name exists for the same object type and a subtype. If an object type does not support any subtypes, such as users or comments, you should commonly call this function without passing a subtype. return: bool True if the meta key was successfully registered in the global array, false if not. param: string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', param: string $meta_key Meta key to register. param: array $args { param: string|array $deprecated Deprecated. Use `$args` instead. since: 3.3.0 since: 4.6.0 {@link https://core.trac.wordpress.org/ticket/35658 Modified 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.5.0 The `$default` argument was added to the arguments array. |
| filter_default_metadata( $value, $object_id, $meta_key, $single, $meta_type ) X-Ref |
| Filters into default_{$object_type}_metadata and adds in default value. return: mixed An array of default values if `$single` is false. param: mixed $value Current value passed to filter. param: int $object_id ID of the object metadata is for. param: string $meta_key Metadata key. param: bool $single If true, return only the first value of the specified `$meta_key`. param: string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', since: 5.5.0 |
| registered_meta_key_exists( $object_type, $meta_key, $object_subtype = '' ) X-Ref |
| Checks if a meta key is registered. return: bool True if the meta key is registered to the object type and, if provided, param: string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', param: string $meta_key Metadata key. param: string $object_subtype Optional. The subtype of the object type. since: 4.6.0 since: 4.9.8 The `$object_subtype` parameter was added. |
| unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) X-Ref |
| Unregisters a meta key from the list of registered keys. return: bool True if successful. False if the meta key was not registered. param: string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', param: string $meta_key Metadata key. param: string $object_subtype Optional. The subtype of the object type. since: 4.6.0 since: 4.9.8 The `$object_subtype` parameter was added. |
| get_registered_meta_keys( $object_type, $object_subtype = '' ) X-Ref |
| Retrieves a list of registered meta keys for an object type. return: string[] List of registered meta keys. param: string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', param: string $object_subtype Optional. The subtype of the object type. since: 4.6.0 since: 4.9.8 The `$object_subtype` parameter was added. |
| get_registered_metadata( $object_type, $object_id, $meta_key = '' ) X-Ref |
| Retrieves registered metadata for a specified object. The results include both meta that is registered specifically for the object's subtype and meta that is registered for the entire object type. return: mixed A single value or array of values for a key if specified. An array of all registered keys param: string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', 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 since: 4.6.0 |
| _wp_register_meta_args_allowed_list( $args, $default_args ) X-Ref |
| Filters out `register_meta()` args based on an allowed list. `register_meta()` args may change over time, so requiring the allowed list to be explicitly turned off is a warranty seal of sorts. return: array Filtered arguments. param: array $args Arguments from `register_meta()`. param: array $default_args Default arguments for `register_meta()`. since: 5.5.0 |
| get_object_subtype( $object_type, $object_id ) X-Ref |
| Returns the object subtype for a given object ID of a specific type. return: string The object subtype or an empty string if unspecified subtype. param: string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', param: int $object_id ID of the object to retrieve its subtype. since: 4.9.8 |
| Generated: Thu Nov 21 01:00:03 2024 | Cross-referenced by PHPXref 0.7.1 |