WordPress 4.4
[autoinstalls/wordpress.git] / wp-includes / meta.php
1 <?php
2 /**
3  * Core Metadata API
4  *
5  * Functions for retrieving and manipulating metadata of various WordPress object types. Metadata
6  * for an object is a represented by a simple key-value pair. Objects may contain multiple
7  * metadata entries that share the same key and differ only in their value.
8  *
9  * @package WordPress
10  * @subpackage Meta
11  */
12
13 /**
14  * Add metadata for the specified object.
15  *
16  * @since 2.9.0
17  *
18  * @global wpdb $wpdb WordPress database abstraction object.
19  *
20  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
21  * @param int    $object_id  ID of the object metadata is for
22  * @param string $meta_key   Metadata key
23  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
24  * @param bool   $unique     Optional, default is false.
25  *                           Whether the specified metadata key should be unique for the object.
26  *                           If true, and the object already has a value for the specified metadata key,
27  *                           no change will be made.
28  * @return int|false The meta ID on success, false on failure.
29  */
30 function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
31         global $wpdb;
32
33         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
34                 return false;
35         }
36
37         $object_id = absint( $object_id );
38         if ( ! $object_id ) {
39                 return false;
40         }
41
42         $table = _get_meta_table( $meta_type );
43         if ( ! $table ) {
44                 return false;
45         }
46
47         $column = sanitize_key($meta_type . '_id');
48
49         // expected_slashed ($meta_key)
50         $meta_key = wp_unslash($meta_key);
51         $meta_value = wp_unslash($meta_value);
52         $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
53
54         /**
55          * Filter whether to add metadata of a specific type.
56          *
57          * The dynamic portion of the hook, `$meta_type`, refers to the meta
58          * object type (comment, post, or user). Returning a non-null value
59          * will effectively short-circuit the function.
60          *
61          * @since 3.1.0
62          *
63          * @param null|bool $check      Whether to allow adding metadata for the given type.
64          * @param int       $object_id  Object ID.
65          * @param string    $meta_key   Meta key.
66          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
67          * @param bool      $unique     Whether the specified meta key should be unique
68          *                              for the object. Optional. Default false.
69          */
70         $check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
71         if ( null !== $check )
72                 return $check;
73
74         if ( $unique && $wpdb->get_var( $wpdb->prepare(
75                 "SELECT COUNT(*) FROM $table WHERE meta_key = %s AND $column = %d",
76                 $meta_key, $object_id ) ) )
77                 return false;
78
79         $_meta_value = $meta_value;
80         $meta_value = maybe_serialize( $meta_value );
81
82         /**
83          * Fires immediately before meta of a specific type is added.
84          *
85          * The dynamic portion of the hook, `$meta_type`, refers to the meta
86          * object type (comment, post, or user).
87          *
88          * @since 3.1.0
89          *
90          * @param int    $object_id  Object ID.
91          * @param string $meta_key   Meta key.
92          * @param mixed  $meta_value Meta value.
93          */
94         do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );
95
96         $result = $wpdb->insert( $table, array(
97                 $column => $object_id,
98                 'meta_key' => $meta_key,
99                 'meta_value' => $meta_value
100         ) );
101
102         if ( ! $result )
103                 return false;
104
105         $mid = (int) $wpdb->insert_id;
106
107         wp_cache_delete($object_id, $meta_type . '_meta');
108
109         /**
110          * Fires immediately after meta of a specific type is added.
111          *
112          * The dynamic portion of the hook, `$meta_type`, refers to the meta
113          * object type (comment, post, or user).
114          *
115          * @since 2.9.0
116          *
117          * @param int    $mid        The meta ID after successful update.
118          * @param int    $object_id  Object ID.
119          * @param string $meta_key   Meta key.
120          * @param mixed  $meta_value Meta value.
121          */
122         do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
123
124         return $mid;
125 }
126
127 /**
128  * Update metadata for the specified object. If no value already exists for the specified object
129  * ID and metadata key, the metadata will be added.
130  *
131  * @since 2.9.0
132  *
133  * @global wpdb $wpdb WordPress database abstraction object.
134  *
135  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
136  * @param int    $object_id  ID of the object metadata is for
137  * @param string $meta_key   Metadata key
138  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
139  * @param mixed  $prev_value Optional. If specified, only update existing metadata entries with
140  *                                   the specified value. Otherwise, update all entries.
141  * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
142  */
143 function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
144         global $wpdb;
145
146         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
147                 return false;
148         }
149
150         $object_id = absint( $object_id );
151         if ( ! $object_id ) {
152                 return false;
153         }
154
155         $table = _get_meta_table( $meta_type );
156         if ( ! $table ) {
157                 return false;
158         }
159
160         $column = sanitize_key($meta_type . '_id');
161         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
162
163         // expected_slashed ($meta_key)
164         $meta_key = wp_unslash($meta_key);
165         $passed_value = $meta_value;
166         $meta_value = wp_unslash($meta_value);
167         $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
168
169         /**
170          * Filter whether to update metadata of a specific type.
171          *
172          * The dynamic portion of the hook, `$meta_type`, refers to the meta
173          * object type (comment, post, or user). Returning a non-null value
174          * will effectively short-circuit the function.
175          *
176          * @since 3.1.0
177          *
178          * @param null|bool $check      Whether to allow updating metadata for the given type.
179          * @param int       $object_id  Object ID.
180          * @param string    $meta_key   Meta key.
181          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
182          * @param mixed     $prev_value Optional. If specified, only update existing
183          *                              metadata entries with the specified value.
184          *                              Otherwise, update all entries.
185          */
186         $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );
187         if ( null !== $check )
188                 return (bool) $check;
189
190         // Compare existing value to new value if no prev value given and the key exists only once.
191         if ( empty($prev_value) ) {
192                 $old_value = get_metadata($meta_type, $object_id, $meta_key);
193                 if ( count($old_value) == 1 ) {
194                         if ( $old_value[0] === $meta_value )
195                                 return false;
196                 }
197         }
198
199         $meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) );
200         if ( empty( $meta_ids ) ) {
201                 return add_metadata($meta_type, $object_id, $meta_key, $passed_value);
202         }
203
204         $_meta_value = $meta_value;
205         $meta_value = maybe_serialize( $meta_value );
206
207         $data  = compact( 'meta_value' );
208         $where = array( $column => $object_id, 'meta_key' => $meta_key );
209
210         if ( !empty( $prev_value ) ) {
211                 $prev_value = maybe_serialize($prev_value);
212                 $where['meta_value'] = $prev_value;
213         }
214
215         foreach ( $meta_ids as $meta_id ) {
216                 /**
217                  * Fires immediately before updating metadata of a specific type.
218                  *
219                  * The dynamic portion of the hook, `$meta_type`, refers to the meta
220                  * object type (comment, post, or user).
221                  *
222                  * @since 2.9.0
223                  *
224                  * @param int    $meta_id    ID of the metadata entry to update.
225                  * @param int    $object_id  Object ID.
226                  * @param string $meta_key   Meta key.
227                  * @param mixed  $meta_value Meta value.
228                  */
229                 do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
230         }
231
232         if ( 'post' == $meta_type ) {
233                 foreach ( $meta_ids as $meta_id ) {
234                         /**
235                          * Fires immediately before updating a post's metadata.
236                          *
237                          * @since 2.9.0
238                          *
239                          * @param int    $meta_id    ID of metadata entry to update.
240                          * @param int    $object_id  Object ID.
241                          * @param string $meta_key   Meta key.
242                          * @param mixed  $meta_value Meta value.
243                          */
244                         do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
245                 }
246         }
247
248         $result = $wpdb->update( $table, $data, $where );
249         if ( ! $result )
250                 return false;
251
252         wp_cache_delete($object_id, $meta_type . '_meta');
253
254         foreach ( $meta_ids as $meta_id ) {
255                 /**
256                  * Fires immediately after updating metadata of a specific type.
257                  *
258                  * The dynamic portion of the hook, `$meta_type`, refers to the meta
259                  * object type (comment, post, or user).
260                  *
261                  * @since 2.9.0
262                  *
263                  * @param int    $meta_id    ID of updated metadata entry.
264                  * @param int    $object_id  Object ID.
265                  * @param string $meta_key   Meta key.
266                  * @param mixed  $meta_value Meta value.
267                  */
268                 do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
269         }
270
271         if ( 'post' == $meta_type ) {
272                 foreach ( $meta_ids as $meta_id ) {
273                         /**
274                          * Fires immediately after updating a post's metadata.
275                          *
276                          * @since 2.9.0
277                          *
278                          * @param int    $meta_id    ID of updated metadata entry.
279                          * @param int    $object_id  Object ID.
280                          * @param string $meta_key   Meta key.
281                          * @param mixed  $meta_value Meta value.
282                          */
283                         do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
284                 }
285         }
286
287         return true;
288 }
289
290 /**
291  * Delete metadata for the specified object.
292  *
293  * @since 2.9.0
294  *
295  * @global wpdb $wpdb WordPress database abstraction object.
296  *
297  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
298  * @param int    $object_id  ID of the object metadata is for
299  * @param string $meta_key   Metadata key
300  * @param mixed  $meta_value Optional. Metadata value. Must be serializable if non-scalar. If specified, only delete
301  *                           metadata entries with this value. Otherwise, delete all entries with the specified meta_key.
302  *                           Pass `null, `false`, or an empty string to skip this check. (For backward compatibility,
303  *                           it is not possible to pass an empty string to delete those entries with an empty string
304  *                           for a value.)
305  * @param bool   $delete_all Optional, default is false. If true, delete matching metadata entries for all objects,
306  *                           ignoring the specified object_id. Otherwise, only delete matching metadata entries for
307  *                           the specified object_id.
308  * @return bool True on successful delete, false on failure.
309  */
310 function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
311         global $wpdb;
312
313         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) && ! $delete_all ) {
314                 return false;
315         }
316
317         $object_id = absint( $object_id );
318         if ( ! $object_id && ! $delete_all ) {
319                 return false;
320         }
321
322         $table = _get_meta_table( $meta_type );
323         if ( ! $table ) {
324                 return false;
325         }
326
327         $type_column = sanitize_key($meta_type . '_id');
328         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
329         // expected_slashed ($meta_key)
330         $meta_key = wp_unslash($meta_key);
331         $meta_value = wp_unslash($meta_value);
332
333         /**
334          * Filter whether to delete metadata of a specific type.
335          *
336          * The dynamic portion of the hook, `$meta_type`, refers to the meta
337          * object type (comment, post, or user). Returning a non-null value
338          * will effectively short-circuit the function.
339          *
340          * @since 3.1.0
341          *
342          * @param null|bool $delete     Whether to allow metadata deletion of the given type.
343          * @param int       $object_id  Object ID.
344          * @param string    $meta_key   Meta key.
345          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
346          * @param bool      $delete_all Whether to delete the matching metadata entries
347          *                              for all objects, ignoring the specified $object_id.
348          *                              Default false.
349          */
350         $check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
351         if ( null !== $check )
352                 return (bool) $check;
353
354         $_meta_value = $meta_value;
355         $meta_value = maybe_serialize( $meta_value );
356
357         $query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );
358
359         if ( !$delete_all )
360                 $query .= $wpdb->prepare(" AND $type_column = %d", $object_id );
361
362         if ( '' !== $meta_value && null !== $meta_value && false !== $meta_value )
363                 $query .= $wpdb->prepare(" AND meta_value = %s", $meta_value );
364
365         $meta_ids = $wpdb->get_col( $query );
366         if ( !count( $meta_ids ) )
367                 return false;
368
369         if ( $delete_all )
370                 $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
371
372         /**
373          * Fires immediately before deleting metadata of a specific type.
374          *
375          * The dynamic portion of the hook, `$meta_type`, refers to the meta
376          * object type (comment, post, or user).
377          *
378          * @since 3.1.0
379          *
380          * @param array  $meta_ids   An array of metadata entry IDs to delete.
381          * @param int    $object_id  Object ID.
382          * @param string $meta_key   Meta key.
383          * @param mixed  $meta_value Meta value.
384          */
385         do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
386
387         // Old-style action.
388         if ( 'post' == $meta_type ) {
389                 /**
390                  * Fires immediately before deleting metadata for a post.
391                  *
392                  * @since 2.9.0
393                  *
394                  * @param array $meta_ids An array of post metadata entry IDs to delete.
395                  */
396                 do_action( 'delete_postmeta', $meta_ids );
397         }
398
399         $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
400
401         $count = $wpdb->query($query);
402
403         if ( !$count )
404                 return false;
405
406         if ( $delete_all ) {
407                 foreach ( (array) $object_ids as $o_id ) {
408                         wp_cache_delete($o_id, $meta_type . '_meta');
409                 }
410         } else {
411                 wp_cache_delete($object_id, $meta_type . '_meta');
412         }
413
414         /**
415          * Fires immediately after deleting metadata of a specific type.
416          *
417          * The dynamic portion of the hook name, `$meta_type`, refers to the meta
418          * object type (comment, post, or user).
419          *
420          * @since 2.9.0
421          *
422          * @param array  $meta_ids   An array of deleted metadata entry IDs.
423          * @param int    $object_id  Object ID.
424          * @param string $meta_key   Meta key.
425          * @param mixed  $meta_value Meta value.
426          */
427         do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
428
429         // Old-style action.
430         if ( 'post' == $meta_type ) {
431                 /**
432                  * Fires immediately after deleting metadata for a post.
433                  *
434                  * @since 2.9.0
435                  *
436                  * @param array $meta_ids An array of deleted post metadata entry IDs.
437                  */
438                 do_action( 'deleted_postmeta', $meta_ids );
439         }
440
441         return true;
442 }
443
444 /**
445  * Retrieve metadata for the specified object.
446  *
447  * @since 2.9.0
448  *
449  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
450  * @param int    $object_id ID of the object metadata is for
451  * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
452  *                                  the specified object.
453  * @param bool   $single    Optional, default is false.
454  *                          If true, return only the first value of the specified meta_key.
455  *                          This parameter has no effect if meta_key is not specified.
456  * @return mixed Single metadata value, or array of values
457  */
458 function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
459         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
460                 return false;
461         }
462
463         $object_id = absint( $object_id );
464         if ( ! $object_id ) {
465                 return false;
466         }
467
468         /**
469          * Filter whether to retrieve metadata of a specific type.
470          *
471          * The dynamic portion of the hook, `$meta_type`, refers to the meta
472          * object type (comment, post, or user). Returning a non-null value
473          * will effectively short-circuit the function.
474          *
475          * @since 3.1.0
476          *
477          * @param null|array|string $value     The value get_metadata() should return - a single metadata value,
478          *                                     or an array of values.
479          * @param int               $object_id Object ID.
480          * @param string            $meta_key  Meta key.
481          * @param bool              $single    Whether to return only the first value of the specified $meta_key.
482          */
483         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
484         if ( null !== $check ) {
485                 if ( $single && is_array( $check ) )
486                         return $check[0];
487                 else
488                         return $check;
489         }
490
491         $meta_cache = wp_cache_get($object_id, $meta_type . '_meta');
492
493         if ( !$meta_cache ) {
494                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
495                 $meta_cache = $meta_cache[$object_id];
496         }
497
498         if ( ! $meta_key ) {
499                 return $meta_cache;
500         }
501
502         if ( isset($meta_cache[$meta_key]) ) {
503                 if ( $single )
504                         return maybe_unserialize( $meta_cache[$meta_key][0] );
505                 else
506                         return array_map('maybe_unserialize', $meta_cache[$meta_key]);
507         }
508
509         if ($single)
510                 return '';
511         else
512                 return array();
513 }
514
515 /**
516  * Determine if a meta key is set for a given object
517  *
518  * @since 3.3.0
519  *
520  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
521  * @param int    $object_id ID of the object metadata is for
522  * @param string $meta_key  Metadata key.
523  * @return bool True of the key is set, false if not.
524  */
525 function metadata_exists( $meta_type, $object_id, $meta_key ) {
526         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
527                 return false;
528         }
529
530         $object_id = absint( $object_id );
531         if ( ! $object_id ) {
532                 return false;
533         }
534
535         /** This filter is documented in wp-includes/meta.php */
536         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, true );
537         if ( null !== $check )
538                 return (bool) $check;
539
540         $meta_cache = wp_cache_get( $object_id, $meta_type . '_meta' );
541
542         if ( !$meta_cache ) {
543                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
544                 $meta_cache = $meta_cache[$object_id];
545         }
546
547         if ( isset( $meta_cache[ $meta_key ] ) )
548                 return true;
549
550         return false;
551 }
552
553 /**
554  * Get meta data by meta ID
555  *
556  * @since 3.3.0
557  *
558  * @global wpdb $wpdb WordPress database abstraction object.
559  *
560  * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
561  * @param int    $meta_id   ID for a specific meta row
562  * @return object|false Meta object or false.
563  */
564 function get_metadata_by_mid( $meta_type, $meta_id ) {
565         global $wpdb;
566
567         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
568                 return false;
569         }
570
571         $meta_id = absint( $meta_id );
572         if ( ! $meta_id ) {
573                 return false;
574         }
575
576         $table = _get_meta_table( $meta_type );
577         if ( ! $table ) {
578                 return false;
579         }
580
581         $id_column = ( 'user' == $meta_type ) ? 'umeta_id' : 'meta_id';
582
583         $meta = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table WHERE $id_column = %d", $meta_id ) );
584
585         if ( empty( $meta ) )
586                 return false;
587
588         if ( isset( $meta->meta_value ) )
589                 $meta->meta_value = maybe_unserialize( $meta->meta_value );
590
591         return $meta;
592 }
593
594 /**
595  * Update meta data by meta ID
596  *
597  * @since 3.3.0
598  *
599  * @global wpdb $wpdb WordPress database abstraction object.
600  *
601  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
602  * @param int    $meta_id    ID for a specific meta row
603  * @param string $meta_value Metadata value
604  * @param string $meta_key   Optional, you can provide a meta key to update it
605  * @return bool True on successful update, false on failure.
606  */
607 function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) {
608         global $wpdb;
609
610         // Make sure everything is valid.
611         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
612                 return false;
613         }
614
615         $meta_id = absint( $meta_id );
616         if ( ! $meta_id ) {
617                 return false;
618         }
619
620         $table = _get_meta_table( $meta_type );
621         if ( ! $table ) {
622                 return false;
623         }
624
625         $column = sanitize_key($meta_type . '_id');
626         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
627
628         // Fetch the meta and go on if it's found.
629         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
630                 $original_key = $meta->meta_key;
631                 $object_id = $meta->{$column};
632
633                 // If a new meta_key (last parameter) was specified, change the meta key,
634                 // otherwise use the original key in the update statement.
635                 if ( false === $meta_key ) {
636                         $meta_key = $original_key;
637                 } elseif ( ! is_string( $meta_key ) ) {
638                         return false;
639                 }
640
641                 // Sanitize the meta
642                 $_meta_value = $meta_value;
643                 $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
644                 $meta_value = maybe_serialize( $meta_value );
645
646                 // Format the data query arguments.
647                 $data = array(
648                         'meta_key' => $meta_key,
649                         'meta_value' => $meta_value
650                 );
651
652                 // Format the where query arguments.
653                 $where = array();
654                 $where[$id_column] = $meta_id;
655
656                 /** This action is documented in wp-includes/meta.php */
657                 do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
658
659                 if ( 'post' == $meta_type ) {
660                         /** This action is documented in wp-includes/meta.php */
661                         do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
662                 }
663
664                 // Run the update query, all fields in $data are %s, $where is a %d.
665                 $result = $wpdb->update( $table, $data, $where, '%s', '%d' );
666                 if ( ! $result )
667                         return false;
668
669                 // Clear the caches.
670                 wp_cache_delete($object_id, $meta_type . '_meta');
671
672                 /** This action is documented in wp-includes/meta.php */
673                 do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
674
675                 if ( 'post' == $meta_type ) {
676                         /** This action is documented in wp-includes/meta.php */
677                         do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
678                 }
679
680                 return true;
681         }
682
683         // And if the meta was not found.
684         return false;
685 }
686
687 /**
688  * Delete meta data by meta ID
689  *
690  * @since 3.3.0
691  *
692  * @global wpdb $wpdb WordPress database abstraction object.
693  *
694  * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
695  * @param int    $meta_id   ID for a specific meta row
696  * @return bool True on successful delete, false on failure.
697  */
698 function delete_metadata_by_mid( $meta_type, $meta_id ) {
699         global $wpdb;
700
701         // Make sure everything is valid.
702         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
703                 return false;
704         }
705
706         $meta_id = absint( $meta_id );
707         if ( ! $meta_id ) {
708                 return false;
709         }
710
711         $table = _get_meta_table( $meta_type );
712         if ( ! $table ) {
713                 return false;
714         }
715
716         // object and id columns
717         $column = sanitize_key($meta_type . '_id');
718         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
719
720         // Fetch the meta and go on if it's found.
721         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
722                 $object_id = $meta->{$column};
723
724                 /** This action is documented in wp-includes/meta.php */
725                 do_action( "delete_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
726
727                 // Old-style action.
728                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
729                         /**
730                          * Fires immediately before deleting post or comment metadata of a specific type.
731                          *
732                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
733                          * object type (post or comment).
734                          *
735                          * @since 3.4.0
736                          *
737                          * @param int $meta_id ID of the metadata entry to delete.
738                          */
739                         do_action( "delete_{$meta_type}meta", $meta_id );
740                 }
741
742                 // Run the query, will return true if deleted, false otherwise
743                 $result = (bool) $wpdb->delete( $table, array( $id_column => $meta_id ) );
744
745                 // Clear the caches.
746                 wp_cache_delete($object_id, $meta_type . '_meta');
747
748                 /** This action is documented in wp-includes/meta.php */
749                 do_action( "deleted_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
750
751                 // Old-style action.
752                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
753                         /**
754                          * Fires immediately after deleting post or comment metadata of a specific type.
755                          *
756                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
757                          * object type (post or comment).
758                          *
759                          * @since 3.4.0
760                          *
761                          * @param int $meta_ids Deleted metadata entry ID.
762                          */
763                         do_action( "deleted_{$meta_type}meta", $meta_id );
764                 }
765
766                 return $result;
767
768         }
769
770         // Meta id was not found.
771         return false;
772 }
773
774 /**
775  * Update the metadata cache for the specified objects.
776  *
777  * @since 2.9.0
778  *
779  * @global wpdb $wpdb WordPress database abstraction object.
780  *
781  * @param string    $meta_type  Type of object metadata is for (e.g., comment, post, or user)
782  * @param int|array $object_ids Array or comma delimited list of object IDs to update cache for
783  * @return array|false Metadata cache for the specified objects, or false on failure.
784  */
785 function update_meta_cache($meta_type, $object_ids) {
786         global $wpdb;
787
788         if ( ! $meta_type || ! $object_ids ) {
789                 return false;
790         }
791
792         $table = _get_meta_table( $meta_type );
793         if ( ! $table ) {
794                 return false;
795         }
796
797         $column = sanitize_key($meta_type . '_id');
798
799         if ( !is_array($object_ids) ) {
800                 $object_ids = preg_replace('|[^0-9,]|', '', $object_ids);
801                 $object_ids = explode(',', $object_ids);
802         }
803
804         $object_ids = array_map('intval', $object_ids);
805
806         $cache_key = $meta_type . '_meta';
807         $ids = array();
808         $cache = array();
809         foreach ( $object_ids as $id ) {
810                 $cached_object = wp_cache_get( $id, $cache_key );
811                 if ( false === $cached_object )
812                         $ids[] = $id;
813                 else
814                         $cache[$id] = $cached_object;
815         }
816
817         if ( empty( $ids ) )
818                 return $cache;
819
820         // Get meta info
821         $id_list = join( ',', $ids );
822         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
823         $meta_list = $wpdb->get_results( "SELECT $column, meta_key, meta_value FROM $table WHERE $column IN ($id_list) ORDER BY $id_column ASC", ARRAY_A );
824
825         if ( !empty($meta_list) ) {
826                 foreach ( $meta_list as $metarow) {
827                         $mpid = intval($metarow[$column]);
828                         $mkey = $metarow['meta_key'];
829                         $mval = $metarow['meta_value'];
830
831                         // Force subkeys to be array type:
832                         if ( !isset($cache[$mpid]) || !is_array($cache[$mpid]) )
833                                 $cache[$mpid] = array();
834                         if ( !isset($cache[$mpid][$mkey]) || !is_array($cache[$mpid][$mkey]) )
835                                 $cache[$mpid][$mkey] = array();
836
837                         // Add a value to the current pid/key:
838                         $cache[$mpid][$mkey][] = $mval;
839                 }
840         }
841
842         foreach ( $ids as $id ) {
843                 if ( ! isset($cache[$id]) )
844                         $cache[$id] = array();
845                 wp_cache_add( $id, $cache[$id], $cache_key );
846         }
847
848         return $cache;
849 }
850
851 /**
852  * Given a meta query, generates SQL clauses to be appended to a main query.
853  *
854  * @since 3.2.0
855  *
856  * @see WP_Meta_Query
857  *
858  * @param array $meta_query         A meta query.
859  * @param string $type              Type of meta.
860  * @param string $primary_table     Primary database table name.
861  * @param string $primary_id_column Primary ID column name.
862  * @param object $context           Optional. The main query object
863  * @return array Associative array of `JOIN` and `WHERE` SQL.
864  */
865 function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) {
866         $meta_query_obj = new WP_Meta_Query( $meta_query );
867         return $meta_query_obj->get_sql( $type, $primary_table, $primary_id_column, $context );
868 }
869
870 /**
871  * Retrieve the name of the metadata table for the specified object type.
872  *
873  * @since 2.9.0
874  *
875  * @global wpdb $wpdb WordPress database abstraction object.
876  *
877  * @param string $type Type of object to get metadata table for (e.g., comment, post, or user)
878  * @return string|false Metadata table name, or false if no metadata table exists
879  */
880 function _get_meta_table($type) {
881         global $wpdb;
882
883         $table_name = $type . 'meta';
884
885         if ( empty($wpdb->$table_name) )
886                 return false;
887
888         return $wpdb->$table_name;
889 }
890
891 /**
892  * Determine whether a meta key is protected.
893  *
894  * @since 3.1.3
895  *
896  * @param string      $meta_key Meta key
897  * @param string|null $meta_type
898  * @return bool True if the key is protected, false otherwise.
899  */
900 function is_protected_meta( $meta_key, $meta_type = null ) {
901         $protected = ( '_' == $meta_key[0] );
902
903         /**
904          * Filter whether a meta key is protected.
905          *
906          * @since 3.2.0
907          *
908          * @param bool   $protected Whether the key is protected. Default false.
909          * @param string $meta_key  Meta key.
910          * @param string $meta_type Meta type.
911          */
912         return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
913 }
914
915 /**
916  * Sanitize meta value.
917  *
918  * @since 3.1.3
919  *
920  * @param string $meta_key   Meta key
921  * @param mixed  $meta_value Meta value to sanitize
922  * @param string $meta_type  Type of meta
923  * @return mixed Sanitized $meta_value
924  */
925 function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
926
927         /**
928          * Filter the sanitization of a specific meta key of a specific meta type.
929          *
930          * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
931          * refer to the metadata object type (comment, post, or user) and the meta
932          * key value,
933          * respectively.
934          *
935          * @since 3.3.0
936          *
937          * @param mixed  $meta_value Meta value to sanitize.
938          * @param string $meta_key   Meta key.
939          * @param string $meta_type  Meta type.
940          */
941         return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
942 }
943
944 /**
945  * Register meta key
946  *
947  * @since 3.3.0
948  *
949  * @param string       $meta_type         Type of meta
950  * @param string       $meta_key          Meta key
951  * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
952  * @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.
953  */
954 function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
955         if ( is_callable( $sanitize_callback ) )
956                 add_filter( "sanitize_{$meta_type}_meta_{$meta_key}", $sanitize_callback, 10, 3 );
957
958         if ( empty( $auth_callback ) ) {
959                 if ( is_protected_meta( $meta_key, $meta_type ) )
960                         $auth_callback = '__return_false';
961                 else
962                         $auth_callback = '__return_true';
963         }
964
965         if ( is_callable( $auth_callback ) )
966                 add_filter( "auth_{$meta_type}_meta_{$meta_key}", $auth_callback, 10, 6 );
967 }