← Back to branch summary

~canonical-sysadmins/wordpress/4.7.2

« back to all changes in this revision

Viewing changes to wp-includes/meta.php

  • Committer: Barry Price
  • Date: 2016-08-17 04:50:12 UTC
  • mfrom: (1.1.18 upstream)
  • Revision ID: barry.price@canonical.com-20160817045012-qfui81zhqnqv2ba9
Merge WP4.6 from upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
wp-includes/meta.php
52
52
        $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
53
53
 
54
54
        /**
55
 
         * Filter whether to add metadata of a specific type.
 
55
         * Filters whether to add metadata of a specific type.
56
56
         *
57
57
         * The dynamic portion of the hook, `$meta_type`, refers to the meta
58
58
         * object type (comment, post, or user). Returning a non-null value
168
168
        $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
169
169
 
170
170
        /**
171
 
         * Filter whether to update metadata of a specific type.
 
171
         * Filters whether to update metadata of a specific type.
172
172
         *
173
173
         * The dynamic portion of the hook, `$meta_type`, refers to the meta
174
174
         * object type (comment, post, or user). Returning a non-null value
328
328
        $meta_value = wp_unslash($meta_value);
329
329
 
330
330
        /**
331
 
         * Filter whether to delete metadata of a specific type.
 
331
         * Filters whether to delete metadata of a specific type.
332
332
         *
333
333
         * The dynamic portion of the hook, `$meta_type`, refers to the meta
334
334
         * object type (comment, post, or user). Returning a non-null value
469
469
        }
470
470
 
471
471
        /**
472
 
         * Filter whether to retrieve metadata of a specific type.
 
472
         * Filters whether to retrieve metadata of a specific type.
473
473
         *
474
474
         * The dynamic portion of the hook, `$meta_type`, refers to the meta
475
475
         * object type (comment, post, or user). Returning a non-null value
921
921
        $protected = ( '_' == $meta_key[0] );
922
922
 
923
923
        /**
924
 
         * Filter whether a meta key is protected.
 
924
         * Filters whether a meta key is protected.
925
925
         *
926
926
         * @since 3.2.0
927
927
         *
937
937
 *
938
938
 * @since 3.1.3
939
939
 *
940
 
 * @param string $meta_key   Meta key
941
 
 * @param mixed  $meta_value Meta value to sanitize
942
 
 * @param string $meta_type  Type of meta
943
 
 * @return mixed Sanitized $meta_value
 
940
 * @param string $meta_key       Meta key.
 
941
 * @param mixed  $meta_value     Meta value to sanitize.
 
942
 * @param string $object_type    Type of object the meta is registered to.
 
943
 *
 
944
 * @return mixed Sanitized $meta_value.
944
945
 */
945
 
function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
946
 
 
 
946
function sanitize_meta( $meta_key, $meta_value, $object_type ) {
947
947
        /**
948
 
         * Filter the sanitization of a specific meta key of a specific meta type.
 
948
         * Filters the sanitization of a specific meta key of a specific meta type.
949
949
         *
950
950
         * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
951
951
         * refer to the metadata object type (comment, post, or user) and the meta
952
 
         * key value,
953
 
         * respectively.
 
952
         * key value, respectively.
954
953
         *
955
954
         * @since 3.3.0
956
955
         *
957
 
         * @param mixed  $meta_value Meta value to sanitize.
958
 
         * @param string $meta_key   Meta key.
959
 
         * @param string $meta_type  Meta type.
 
956
         * @param mixed  $meta_value      Meta value to sanitize.
 
957
         * @param string $meta_key        Meta key.
 
958
         * @param string $object_type     Object type.
960
959
         */
961
 
        return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
 
960
        return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}", $meta_value, $meta_key, $object_type );
962
961
}
963
962
 
964
963
/**
965
 
 * Register meta key
 
964
 * Registers a meta key.
966
965
 *
967
966
 * @since 3.3.0
968
 
 *
969
 
 * @param string       $meta_type         Type of meta
970
 
 * @param string       $meta_key          Meta key
971
 
 * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
972
 
 * @param string|array $auth_callback     Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks.
973
 
 */
974
 
function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
975
 
        if ( is_callable( $sanitize_callback ) )
976
 
                add_filter( "sanitize_{$meta_type}_meta_{$meta_key}", $sanitize_callback, 10, 3 );
977
 
 
978
 
        if ( empty( $auth_callback ) ) {
979
 
                if ( is_protected_meta( $meta_key, $meta_type ) )
980
 
                        $auth_callback = '__return_false';
981
 
                else
982
 
                        $auth_callback = '__return_true';
983
 
        }
984
 
 
985
 
        if ( is_callable( $auth_callback ) )
986
 
                add_filter( "auth_{$meta_type}_meta_{$meta_key}", $auth_callback, 10, 6 );
 
967
 * @since 4.6.0 {@link https://make.wordpress.org/core/2016/07/08/enhancing-register_meta-in-4-6/ Modified
 
968
 *              to support an array of data to attach to registered meta keys}. Previous arguments for
 
969
 *              `$sanitize_callback` and `$auth_callback` have been folded into this array.
 
970
 *
 
971
 * @param string $object_type    Type of object this meta is registered to.
 
972
 * @param string $meta_key       Meta key to register.
 
973
 * @param array  $args {
 
974
 *     Data used to describe the meta key when registered.
 
975
 *
 
976
 *     @type string $type              The type of data associated with this meta key.
 
977
 *     @type string $description       A description of the data attached to this meta key.
 
978
 *     @type bool   $single            Whether the meta key has one value per object, or an array of values per object.
 
979
 *     @type string $sanitize_callback A function or method to call when sanitizing `$meta_key` data.
 
980
 *     @type string $auth_callback     Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks.
 
981
 *     @type bool   $show_in_rest      Whether data associated with this meta key can be considered public.
 
982
 * }
 
983
 * @param string|array $deprecated Deprecated. Use `$args` instead.
 
984
 *
 
985
 * @return bool True if the meta key was successfully registered in the global array, false if not.
 
986
 *                       Registering a meta key with distinct sanitize and auth callbacks will fire those
 
987
 *                       callbacks, but will not add to the global registry.
 
988
 */
 
989
function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
 
990
        global $wp_meta_keys;
 
991
 
 
992
        if ( ! is_array( $wp_meta_keys ) ) {
 
993
                $wp_meta_keys = array();
 
994
        }
 
995
 
 
996
        $defaults = array(
 
997
                'type'              => 'string',
 
998
                'description'       => '',
 
999
                'single'            => false,
 
1000
                'sanitize_callback' => null,
 
1001
                'auth_callback'     => null,
 
1002
                'show_in_rest'      => false,
 
1003
        );
 
1004
 
 
1005
        // There used to be individual args for sanitize and auth callbacks
 
1006
        $has_old_sanitize_cb = false;
 
1007
        $has_old_auth_cb = false;
 
1008
 
 
1009
        if ( is_callable( $args ) ) {
 
1010
                $args = array(
 
1011
                        'sanitize_callback' => $args,
 
1012
                );
 
1013
 
 
1014
                $has_old_sanitize_cb = true;
 
1015
        } else {
 
1016
                $args = (array) $args;
 
1017
        }
 
1018
 
 
1019
        if ( is_callable( $deprecated ) ) {
 
1020
                $args['auth_callback'] = $deprecated;
 
1021
                $has_old_auth_cb = true;
 
1022
        }
 
1023
 
 
1024
        /**
 
1025
         * Filters the registration arguments when registering meta.
 
1026
         *
 
1027
         * @since 4.6.0
 
1028
         *
 
1029
         * @param array  $args        Array of meta registration arguments.
 
1030
         * @param array  $defaults    Array of default arguments.
 
1031
         * @param string $object_type Object type.
 
1032
         * @param string $meta_key    Meta key.
 
1033
         */
 
1034
        $args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key );
 
1035
        $args = wp_parse_args( $args, $defaults );
 
1036
 
 
1037
        // If `auth_callback` is not provided, fall back to `is_protected_meta()`.
 
1038
        if ( empty( $args['auth_callback'] ) ) {
 
1039
                if ( is_protected_meta( $meta_key, $object_type ) ) {
 
1040
                        $args['auth_callback'] = '__return_false';
 
1041
                } else {
 
1042
                        $args['auth_callback'] = '__return_true';
 
1043
                }
 
1044
        }
 
1045
 
 
1046
        // Back-compat: old sanitize and auth callbacks are applied to all of an object type.
 
1047
        if ( is_callable( $args['sanitize_callback'] ) ) {
 
1048
                add_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'], 10, 3 );
 
1049
        }
 
1050
 
 
1051
        if ( is_callable( $args['auth_callback'] ) ) {
 
1052
                add_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'], 10, 6 );
 
1053
        }
 
1054
 
 
1055
        // Global registry only contains meta keys registered with the array of arguments added in 4.6.0.
 
1056
        if ( ! $has_old_auth_cb && ! $has_old_sanitize_cb ) {
 
1057
                $wp_meta_keys[ $object_type ][ $meta_key ] = $args;
 
1058
 
 
1059
                return true;
 
1060
        }
 
1061
 
 
1062
        return false;
 
1063
}
 
1064
 
 
1065
/**
 
1066
 * Checks if a meta key is registered.
 
1067
 *
 
1068
 * @since 4.6.0
 
1069
 *
 
1070
 * @param string $object_type    The type of object.
 
1071
 * @param string $meta_key       The meta key.
 
1072
 *
 
1073
 * @return bool True if the meta key is registered to the object type. False if not.
 
1074
 */
 
1075
function registered_meta_key_exists( $object_type, $meta_key ) {
 
1076
        global $wp_meta_keys;
 
1077
 
 
1078
        if ( ! is_array( $wp_meta_keys ) ) {
 
1079
                return false;
 
1080
        }
 
1081
 
 
1082
        if ( ! isset( $wp_meta_keys[ $object_type ] ) ) {
 
1083
                return false;
 
1084
        }
 
1085
 
 
1086
        if ( isset( $wp_meta_keys[ $object_type ][ $meta_key ] ) ) {
 
1087
                return true;
 
1088
        }
 
1089
 
 
1090
        return false;
 
1091
}
 
1092
 
 
1093
/**
 
1094
 * Unregisters a meta key from the list of registered keys.
 
1095
 *
 
1096
 * @since 4.6.0
 
1097
 *
 
1098
 * @param string $object_type The type of object.
 
1099
 * @param string $meta_key    The meta key.
 
1100
 * @return bool True if successful. False if the meta key was not registered.
 
1101
 */
 
1102
function unregister_meta_key( $object_type, $meta_key ) {
 
1103
        global $wp_meta_keys;
 
1104
 
 
1105
        if ( ! registered_meta_key_exists( $object_type, $meta_key ) ) {
 
1106
                return false;
 
1107
        }
 
1108
 
 
1109
        $args = $wp_meta_keys[ $object_type ][ $meta_key ];
 
1110
 
 
1111
        if ( isset( $args['sanitize_callback'] ) && is_callable( $args['sanitize_callback'] ) ) {
 
1112
                remove_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'] );
 
1113
        }
 
1114
 
 
1115
        if ( isset( $args['auth_callback'] ) && is_callable( $args['auth_callback'] ) ) {
 
1116
                remove_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'] );
 
1117
        }
 
1118
 
 
1119
        unset( $wp_meta_keys[ $object_type ][ $meta_key ] );
 
1120
 
 
1121
        // Do some clean up
 
1122
        if ( empty( $wp_meta_keys[ $object_type ] ) ) {
 
1123
                unset( $wp_meta_keys[ $object_type ] );
 
1124
        }
 
1125
 
 
1126
        return true;
 
1127
}
 
1128
 
 
1129
/**
 
1130
 * Retrieves a list of registered meta keys for an object type.
 
1131
 *
 
1132
 * @since 4.6.0
 
1133
 *
 
1134
 * @param string $object_type The type of object. Post, comment, user, term.
 
1135
 * @return array List of registered meta keys.
 
1136
 */
 
1137
function get_registered_meta_keys( $object_type ) {
 
1138
        global $wp_meta_keys;
 
1139
 
 
1140
        if ( ! is_array( $wp_meta_keys ) || ! isset( $wp_meta_keys[ $object_type ] ) ) {
 
1141
                return array();
 
1142
        }
 
1143
 
 
1144
        return $wp_meta_keys[ $object_type ];
 
1145
}
 
1146
 
 
1147
/**
 
1148
 * Retrieves registered metadata for a specified object.
 
1149
 *
 
1150
 * @since 4.6.0
 
1151
 *
 
1152
 * @param string $object_type Type of object to request metadata for. (e.g. comment, post, term, user)
 
1153
 * @param int    $object_id   ID of the object the metadata is for.
 
1154
 * @param string $meta_key    Optional. Registered metadata key. If not specified, retrieve all registered
 
1155
 *                            metadata for the specified object.
 
1156
 * @return mixed A single value or array of values for a key if specified. An array of all registered keys
 
1157
 *               and values for an object ID if not.
 
1158
 */
 
1159
function get_registered_metadata( $object_type, $object_id, $meta_key = '' ) {
 
1160
        if ( ! empty( $meta_key ) ) {
 
1161
                if ( ! registered_meta_key_exists( $object_type, $meta_key ) ) {
 
1162
                        return false;
 
1163
                }
 
1164
                $meta_keys = get_registered_meta_keys( $object_type );
 
1165
                $meta_key_data = $meta_keys[ $meta_key ];
 
1166
 
 
1167
                $data = get_metadata( $object_type, $object_id, $meta_key, $meta_key_data['single'] );
 
1168
 
 
1169
                return $data;
 
1170
        }
 
1171
 
 
1172
        $data = get_metadata( $object_type, $object_id );
 
1173
 
 
1174
        $meta_keys = get_registered_meta_keys( $object_type );
 
1175
        $registered_data = array();
 
1176
 
 
1177
        // Someday, array_filter()
 
1178
        foreach ( $meta_keys as $k => $v ) {
 
1179
                if ( isset( $data[ $k ] ) ) {
 
1180
                        $registered_data[ $k ] = $data[ $k ];
 
1181
                }
 
1182
        }
 
1183
 
 
1184
        return $registered_data;
 
1185
}
 
1186
 
 
1187
/**
 
1188
 * Filter out `register_meta()` args based on a whitelist.
 
1189
 * `register_meta()` args may change over time, so requiring the whitelist
 
1190
 * to be explicitly turned off is a warranty seal of sorts.
 
1191
 *
 
1192
 * @access private
 
1193
 * @since  4.6.0
 
1194
 *
 
1195
 * @param  array $args         Arguments from `register_meta()`.
 
1196
 * @param  array $default_args Default arguments for `register_meta()`.
 
1197
 *
 
1198
 * @return array Filtered arguments.
 
1199
 */
 
1200
function _wp_register_meta_args_whitelist( $args, $default_args ) {
 
1201
        $whitelist = array_keys( $default_args );
 
1202
 
 
1203
        // In an anonymous function world, this would be better as an array_filter()
 
1204
        foreach ( $args as $key => $value ) {
 
1205
                if ( ! in_array( $key, $whitelist ) ) {
 
1206
                        unset( $args[ $key ] );
 
1207
                }
 
1208
        }
 
1209
 
 
1210
        return $args;
987
1211
}