WordPress 4.1.1-scripts
[autoinstalls/wordpress.git] / wp-includes / meta.php
1 <?php
2 /**
3  * 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  * @since 2.9.0
12  */
13
14 /**
15  * Add metadata for the specified object.
16  *
17  * @since 2.9.0
18  *
19  * @global wpdb $wpdb WordPress database abstraction object.
20  *
21  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
22  * @param int $object_id ID of the object metadata is for
23  * @param string $meta_key Metadata key
24  * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
25  * @param bool $unique Optional, default is false. Whether the specified metadata key should be
26  *              unique for the object. If true, and the object already has a value for the specified
27  *              metadata key, no change will be made
28  * @return int|bool 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 metadata entries
301  *              with this value. Otherwise, delete all entries with the specified meta_key.
302  * @param bool $delete_all Optional, default is false. If true, delete matching metadata entries
303  *              for all objects, ignoring the specified object_id. Otherwise, only delete matching
304  *              metadata entries for the specified object_id.
305  * @return bool True on successful delete, false on failure.
306  */
307 function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
308         global $wpdb;
309
310         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) && ! $delete_all ) {
311                 return false;
312         }
313
314         $object_id = absint( $object_id );
315         if ( ! $object_id && ! $delete_all ) {
316                 return false;
317         }
318
319         $table = _get_meta_table( $meta_type );
320         if ( ! $table ) {
321                 return false;
322         }
323
324         $type_column = sanitize_key($meta_type . '_id');
325         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
326         // expected_slashed ($meta_key)
327         $meta_key = wp_unslash($meta_key);
328         $meta_value = wp_unslash($meta_value);
329
330         /**
331          * Filter whether to delete metadata of a specific type.
332          *
333          * The dynamic portion of the hook, `$meta_type`, refers to the meta
334          * object type (comment, post, or user). Returning a non-null value
335          * will effectively short-circuit the function.
336          *
337          * @since 3.1.0
338          *
339          * @param null|bool $delete     Whether to allow metadata deletion of the given type.
340          * @param int       $object_id  Object ID.
341          * @param string    $meta_key   Meta key.
342          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
343          * @param bool      $delete_all Whether to delete the matching metadata entries
344          *                              for all objects, ignoring the specified $object_id.
345          *                              Default false.
346          */
347         $check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
348         if ( null !== $check )
349                 return (bool) $check;
350
351         $_meta_value = $meta_value;
352         $meta_value = maybe_serialize( $meta_value );
353
354         $query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );
355
356         if ( !$delete_all )
357                 $query .= $wpdb->prepare(" AND $type_column = %d", $object_id );
358
359         if ( $meta_value )
360                 $query .= $wpdb->prepare(" AND meta_value = %s", $meta_value );
361
362         $meta_ids = $wpdb->get_col( $query );
363         if ( !count( $meta_ids ) )
364                 return false;
365
366         if ( $delete_all )
367                 $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
368
369         /**
370          * Fires immediately before deleting metadata of a specific type.
371          *
372          * The dynamic portion of the hook, `$meta_type`, refers to the meta
373          * object type (comment, post, or user).
374          *
375          * @since 3.1.0
376          *
377          * @param array  $meta_ids   An array of metadata entry IDs to delete.
378          * @param int    $object_id  Object ID.
379          * @param string $meta_key   Meta key.
380          * @param mixed  $meta_value Meta value.
381          */
382         do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
383
384         // Old-style action.
385         if ( 'post' == $meta_type ) {
386                 /**
387                  * Fires immediately before deleting metadata for a post.
388                  *
389                  * @since 2.9.0
390                  *
391                  * @param array $meta_ids An array of post metadata entry IDs to delete.
392                  */
393                 do_action( 'delete_postmeta', $meta_ids );
394         }
395
396         $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
397
398         $count = $wpdb->query($query);
399
400         if ( !$count )
401                 return false;
402
403         if ( $delete_all ) {
404                 foreach ( (array) $object_ids as $o_id ) {
405                         wp_cache_delete($o_id, $meta_type . '_meta');
406                 }
407         } else {
408                 wp_cache_delete($object_id, $meta_type . '_meta');
409         }
410
411         /**
412          * Fires immediately after deleting metadata of a specific type.
413          *
414          * The dynamic portion of the hook name, `$meta_type`, refers to the meta
415          * object type (comment, post, or user).
416          *
417          * @since 2.9.0
418          *
419          * @param array  $meta_ids   An array of deleted metadata entry IDs.
420          * @param int    $object_id  Object ID.
421          * @param string $meta_key   Meta key.
422          * @param mixed  $meta_value Meta value.
423          */
424         do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
425
426         // Old-style action.
427         if ( 'post' == $meta_type ) {
428                 /**
429                  * Fires immediately after deleting metadata for a post.
430                  *
431                  * @since 2.9.0
432                  *
433                  * @param array $meta_ids An array of deleted post metadata entry IDs.
434                  */
435                 do_action( 'deleted_postmeta', $meta_ids );
436         }
437
438         return true;
439 }
440
441 /**
442  * Retrieve metadata for the specified object.
443  *
444  * @since 2.9.0
445  *
446  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
447  * @param int $object_id ID of the object metadata is for
448  * @param string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for
449  *              the specified object.
450  * @param bool $single Optional, default is false. If true, return only the first value of the
451  *              specified meta_key. This parameter has no effect if meta_key is not specified.
452  * @return string|array Single metadata value, or array of values
453  */
454 function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
455         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
456                 return false;
457         }
458
459         $object_id = absint( $object_id );
460         if ( ! $object_id ) {
461                 return false;
462         }
463
464         /**
465          * Filter whether to retrieve metadata of a specific type.
466          *
467          * The dynamic portion of the hook, `$meta_type`, refers to the meta
468          * object type (comment, post, or user). Returning a non-null value
469          * will effectively short-circuit the function.
470          *
471          * @since 3.1.0
472          *
473          * @param null|array|string $value     The value get_metadata() should
474          *                                     return - a single metadata value,
475          *                                     or an array of values.
476          * @param int               $object_id Object ID.
477          * @param string            $meta_key  Meta key.
478          * @param string|array      $single    Meta value, or an array of values.
479          */
480         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
481         if ( null !== $check ) {
482                 if ( $single && is_array( $check ) )
483                         return $check[0];
484                 else
485                         return $check;
486         }
487
488         $meta_cache = wp_cache_get($object_id, $meta_type . '_meta');
489
490         if ( !$meta_cache ) {
491                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
492                 $meta_cache = $meta_cache[$object_id];
493         }
494
495         if ( ! $meta_key ) {
496                 return $meta_cache;
497         }
498
499         if ( isset($meta_cache[$meta_key]) ) {
500                 if ( $single )
501                         return maybe_unserialize( $meta_cache[$meta_key][0] );
502                 else
503                         return array_map('maybe_unserialize', $meta_cache[$meta_key]);
504         }
505
506         if ($single)
507                 return '';
508         else
509                 return array();
510 }
511
512 /**
513  * Determine if a meta key is set for a given object
514  *
515  * @since 3.3.0
516  *
517  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
518  * @param int $object_id ID of the object metadata is for
519  * @param string $meta_key Metadata key.
520  * @return boolean true of the key is set, false if not.
521  */
522 function metadata_exists( $meta_type, $object_id, $meta_key ) {
523         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
524                 return false;
525         }
526
527         $object_id = absint( $object_id );
528         if ( ! $object_id ) {
529                 return false;
530         }
531
532         /** This filter is documented in wp-includes/meta.php */
533         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, true );
534         if ( null !== $check )
535                 return (bool) $check;
536
537         $meta_cache = wp_cache_get( $object_id, $meta_type . '_meta' );
538
539         if ( !$meta_cache ) {
540                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
541                 $meta_cache = $meta_cache[$object_id];
542         }
543
544         if ( isset( $meta_cache[ $meta_key ] ) )
545                 return true;
546
547         return false;
548 }
549
550 /**
551  * Get meta data by meta ID
552  *
553  * @since 3.3.0
554  *
555  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
556  * @param int $meta_id ID for a specific meta row
557  * @return object Meta object or false.
558  */
559 function get_metadata_by_mid( $meta_type, $meta_id ) {
560         global $wpdb;
561
562         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
563                 return false;
564         }
565
566         $meta_id = absint( $meta_id );
567         if ( ! $meta_id ) {
568                 return false;
569         }
570
571         $table = _get_meta_table( $meta_type );
572         if ( ! $table ) {
573                 return false;
574         }
575
576         $id_column = ( 'user' == $meta_type ) ? 'umeta_id' : 'meta_id';
577
578         $meta = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table WHERE $id_column = %d", $meta_id ) );
579
580         if ( empty( $meta ) )
581                 return false;
582
583         if ( isset( $meta->meta_value ) )
584                 $meta->meta_value = maybe_unserialize( $meta->meta_value );
585
586         return $meta;
587 }
588
589 /**
590  * Update meta data by meta ID
591  *
592  * @since 3.3.0
593  *
594  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
595  * @param int $meta_id ID for a specific meta row
596  * @param string $meta_value Metadata value
597  * @param string $meta_key Optional, you can provide a meta key to update it
598  * @return bool True on successful update, false on failure.
599  */
600 function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) {
601         global $wpdb;
602
603         // Make sure everything is valid.
604         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
605                 return false;
606         }
607
608         $meta_id = absint( $meta_id );
609         if ( ! $meta_id ) {
610                 return false;
611         }
612
613         $table = _get_meta_table( $meta_type );
614         if ( ! $table ) {
615                 return false;
616         }
617
618         $column = sanitize_key($meta_type . '_id');
619         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
620
621         // Fetch the meta and go on if it's found.
622         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
623                 $original_key = $meta->meta_key;
624                 $object_id = $meta->{$column};
625
626                 // If a new meta_key (last parameter) was specified, change the meta key,
627                 // otherwise use the original key in the update statement.
628                 if ( false === $meta_key ) {
629                         $meta_key = $original_key;
630                 } elseif ( ! is_string( $meta_key ) ) {
631                         return false;
632                 }
633
634                 // Sanitize the meta
635                 $_meta_value = $meta_value;
636                 $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
637                 $meta_value = maybe_serialize( $meta_value );
638
639                 // Format the data query arguments.
640                 $data = array(
641                         'meta_key' => $meta_key,
642                         'meta_value' => $meta_value
643                 );
644
645                 // Format the where query arguments.
646                 $where = array();
647                 $where[$id_column] = $meta_id;
648
649                 /** This action is documented in wp-includes/meta.php */
650                 do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
651
652                 if ( 'post' == $meta_type ) {
653                         /** This action is documented in wp-includes/meta.php */
654                         do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
655                 }
656
657                 // Run the update query, all fields in $data are %s, $where is a %d.
658                 $result = $wpdb->update( $table, $data, $where, '%s', '%d' );
659                 if ( ! $result )
660                         return false;
661
662                 // Clear the caches.
663                 wp_cache_delete($object_id, $meta_type . '_meta');
664
665                 /** This action is documented in wp-includes/meta.php */
666                 do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
667
668                 if ( 'post' == $meta_type ) {
669                         /** This action is documented in wp-includes/meta.php */
670                         do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
671                 }
672
673                 return true;
674         }
675
676         // And if the meta was not found.
677         return false;
678 }
679
680 /**
681  * Delete meta data by meta ID
682  *
683  * @since 3.3.0
684  *
685  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
686  * @param int $meta_id ID for a specific meta row
687  * @return bool True on successful delete, false on failure.
688  */
689 function delete_metadata_by_mid( $meta_type, $meta_id ) {
690         global $wpdb;
691
692         // Make sure everything is valid.
693         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
694                 return false;
695         }
696
697         $meta_id = absint( $meta_id );
698         if ( ! $meta_id ) {
699                 return false;
700         }
701
702         $table = _get_meta_table( $meta_type );
703         if ( ! $table ) {
704                 return false;
705         }
706
707         // object and id columns
708         $column = sanitize_key($meta_type . '_id');
709         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
710
711         // Fetch the meta and go on if it's found.
712         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
713                 $object_id = $meta->{$column};
714
715                 /** This action is documented in wp-includes/meta.php */
716                 do_action( "delete_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
717
718                 // Old-style action.
719                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
720                         /**
721                          * Fires immediately before deleting post or comment metadata of a specific type.
722                          *
723                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
724                          * object type (post or comment).
725                          *
726                          * @since 3.4.0
727                          *
728                          * @param int $meta_id ID of the metadata entry to delete.
729                          */
730                         do_action( "delete_{$meta_type}meta", $meta_id );
731                 }
732
733                 // Run the query, will return true if deleted, false otherwise
734                 $result = (bool) $wpdb->delete( $table, array( $id_column => $meta_id ) );
735
736                 // Clear the caches.
737                 wp_cache_delete($object_id, $meta_type . '_meta');
738
739                 /** This action is documented in wp-includes/meta.php */
740                 do_action( "deleted_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
741
742                 // Old-style action.
743                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
744                         /**
745                          * Fires immediately after deleting post or comment metadata of a specific type.
746                          *
747                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
748                          * object type (post or comment).
749                          *
750                          * @since 3.4.0
751                          *
752                          * @param int $meta_ids Deleted metadata entry ID.
753                          */
754                         do_action( "deleted_{$meta_type}meta", $meta_id );
755                 }
756
757                 return $result;
758
759         }
760
761         // Meta id was not found.
762         return false;
763 }
764
765 /**
766  * Update the metadata cache for the specified objects.
767  *
768  * @since 2.9.0
769  *
770  * @global wpdb $wpdb WordPress database abstraction object.
771  *
772  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
773  * @param int|array $object_ids array or comma delimited list of object IDs to update cache for
774  * @return mixed Metadata cache for the specified objects, or false on failure.
775  */
776 function update_meta_cache($meta_type, $object_ids) {
777         global $wpdb;
778
779         if ( ! $meta_type || ! $object_ids ) {
780                 return false;
781         }
782
783         $table = _get_meta_table( $meta_type );
784         if ( ! $table ) {
785                 return false;
786         }
787
788         $column = sanitize_key($meta_type . '_id');
789
790         if ( !is_array($object_ids) ) {
791                 $object_ids = preg_replace('|[^0-9,]|', '', $object_ids);
792                 $object_ids = explode(',', $object_ids);
793         }
794
795         $object_ids = array_map('intval', $object_ids);
796
797         $cache_key = $meta_type . '_meta';
798         $ids = array();
799         $cache = array();
800         foreach ( $object_ids as $id ) {
801                 $cached_object = wp_cache_get( $id, $cache_key );
802                 if ( false === $cached_object )
803                         $ids[] = $id;
804                 else
805                         $cache[$id] = $cached_object;
806         }
807
808         if ( empty( $ids ) )
809                 return $cache;
810
811         // Get meta info
812         $id_list = join( ',', $ids );
813         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
814         $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 );
815
816         if ( !empty($meta_list) ) {
817                 foreach ( $meta_list as $metarow) {
818                         $mpid = intval($metarow[$column]);
819                         $mkey = $metarow['meta_key'];
820                         $mval = $metarow['meta_value'];
821
822                         // Force subkeys to be array type:
823                         if ( !isset($cache[$mpid]) || !is_array($cache[$mpid]) )
824                                 $cache[$mpid] = array();
825                         if ( !isset($cache[$mpid][$mkey]) || !is_array($cache[$mpid][$mkey]) )
826                                 $cache[$mpid][$mkey] = array();
827
828                         // Add a value to the current pid/key:
829                         $cache[$mpid][$mkey][] = $mval;
830                 }
831         }
832
833         foreach ( $ids as $id ) {
834                 if ( ! isset($cache[$id]) )
835                         $cache[$id] = array();
836                 wp_cache_add( $id, $cache[$id], $cache_key );
837         }
838
839         return $cache;
840 }
841
842 /**
843  * Given a meta query, generates SQL clauses to be appended to a main query.
844  *
845  * @since 3.2.0
846  *
847  * @see WP_Meta_Query
848  *
849  * @param array $meta_query         A meta query.
850  * @param string $type              Type of meta.
851  * @param string $primary_table     Primary database table name.
852  * @param string $primary_id_column Primary ID column name.
853  * @param object $context           Optional. The main query object
854  * @return array Associative array of `JOIN` and `WHERE` SQL.
855  */
856 function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) {
857         $meta_query_obj = new WP_Meta_Query( $meta_query );
858         return $meta_query_obj->get_sql( $type, $primary_table, $primary_id_column, $context );
859 }
860
861 /**
862  * Class for generating SQL clauses that filter a primary query according to metadata keys and values.
863  *
864  * `WP_Meta_Query` is a helper that allows primary query classes, such as {@see WP_Query} and {@see WP_User_Query},
865  * to filter their results by object metadata, by generating `JOIN` and `WHERE` subclauses to be attached
866  * to the primary SQL query string.
867  *
868  * @since 3.2.0
869  */
870 class WP_Meta_Query {
871         /**
872          * Array of metadata queries.
873          *
874          * See {@see WP_Meta_Query::__construct()} for information on meta query arguments.
875          *
876          * @since 3.2.0
877          * @access public
878          * @var array
879          */
880         public $queries = array();
881
882         /**
883          * The relation between the queries. Can be one of 'AND' or 'OR'.
884          *
885          * @since 3.2.0
886          * @access public
887          * @var string
888          */
889         public $relation;
890
891         /**
892          * Database table to query for the metadata.
893          *
894          * @since 4.1.0
895          * @access public
896          * @var string
897          */
898         public $meta_table;
899
900         /**
901          * Column in meta_table that represents the ID of the object the metadata belongs to.
902          *
903          * @since 4.1.0
904          * @access public
905          * @var string
906          */
907         public $meta_id_column;
908
909         /**
910          * Database table that where the metadata's objects are stored (eg $wpdb->users).
911          *
912          * @since 4.1.0
913          * @access public
914          * @var string
915          */
916         public $primary_table;
917
918         /**
919          * Column in primary_table that represents the ID of the object.
920          *
921          * @since 4.1.0
922          * @access public
923          * @var string
924          */
925         public $primary_id_column;
926
927         /**
928          * A flat list of table aliases used in JOIN clauses.
929          *
930          * @since 4.1.0
931          * @access protected
932          * @var array
933          */
934         protected $table_aliases = array();
935
936         /**
937          * Constructor.
938          *
939          * @since 3.2.0
940          * @access public
941          *
942          * @param array $meta_query {
943          *     Array of meta query clauses.
944          *
945          *     @type string $relation Optional. The MySQL keyword used to join
946          *                            the clauses of the query. Accepts 'AND', or 'OR'. Default 'AND'.
947          *     @type array {
948          *         Optional. An array of first-order clause parameters, or another fully-formed meta query.
949          *
950          *         @type string $key     Meta key to filter by.
951          *         @type string $value   Meta value to filter by.
952          *         @type string $compare MySQL operator used for comparing the $value. Accepts '=',
953          *                               '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN',
954          *                               'BETWEEN', 'NOT BETWEEN', 'REGEXP', 'NOT REGEXP', or 'RLIKE'.
955          *                               Default is 'IN' when `$value` is an array, '=' otherwise.
956          *         @type string $type    MySQL data type that the meta_value column will be CAST to for
957          *                               comparisons. Accepts 'NUMERIC', 'BINARY', 'CHAR', 'DATE',
958          *                               'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', or 'UNSIGNED'.
959          *                               Default is 'CHAR'.
960          *     }
961          * }
962          */
963         public function __construct( $meta_query = false ) {
964                 if ( !$meta_query )
965                         return;
966
967                 if ( isset( $meta_query['relation'] ) && strtoupper( $meta_query['relation'] ) == 'OR' ) {
968                         $this->relation = 'OR';
969                 } else {
970                         $this->relation = 'AND';
971                 }
972
973                 $this->queries = $this->sanitize_query( $meta_query );
974         }
975
976         /**
977          * Ensure the 'meta_query' argument passed to the class constructor is well-formed.
978          *
979          * Eliminates empty items and ensures that a 'relation' is set.
980          *
981          * @since 4.1.0
982          * @access public
983          *
984          * @param array $queries Array of query clauses.
985          * @return array Sanitized array of query clauses.
986          */
987         public function sanitize_query( $queries ) {
988                 $clean_queries = array();
989
990                 if ( ! is_array( $queries ) ) {
991                         return $clean_queries;
992                 }
993
994                 foreach ( $queries as $key => $query ) {
995                         if ( 'relation' === $key ) {
996                                 $relation = $query;
997
998                         } else if ( ! is_array( $query ) ) {
999                                 continue;
1000
1001                         // First-order clause.
1002                         } else if ( $this->is_first_order_clause( $query ) ) {
1003                                 if ( isset( $query['value'] ) && array() === $query['value'] ) {
1004                                         unset( $query['value'] );
1005                                 }
1006
1007                                 $clean_queries[] = $query;
1008
1009                         // Otherwise, it's a nested query, so we recurse.
1010                         } else {
1011                                 $cleaned_query = $this->sanitize_query( $query );
1012
1013                                 if ( ! empty( $cleaned_query ) ) {
1014                                         $clean_queries[] = $cleaned_query;
1015                                 }
1016                         }
1017                 }
1018
1019                 if ( empty( $clean_queries ) ) {
1020                         return $clean_queries;
1021                 }
1022
1023                 // Sanitize the 'relation' key provided in the query.
1024                 if ( isset( $relation ) && 'OR' === strtoupper( $relation ) ) {
1025                         $clean_queries['relation'] = 'OR';
1026
1027                 /*
1028                  * If there is only a single clause, call the relation 'OR'.
1029                  * This value will not actually be used to join clauses, but it
1030                  * simplifies the logic around combining key-only queries.
1031                  */
1032                 } else if ( 1 === count( $clean_queries ) ) {
1033                         $clean_queries['relation'] = 'OR';
1034
1035                 // Default to AND.
1036                 } else {
1037                         $clean_queries['relation'] = 'AND';
1038                 }
1039
1040                 return $clean_queries;
1041         }
1042
1043         /**
1044          * Determine whether a query clause is first-order.
1045          *
1046          * A first-order meta query clause is one that has either a 'key' or
1047          * a 'value' array key.
1048          *
1049          * @since 4.1.0
1050          * @access protected
1051          *
1052          * @param array $query Meta query arguments.
1053          * @return bool Whether the query clause is a first-order clause.
1054          */
1055         protected function is_first_order_clause( $query ) {
1056                 return isset( $query['key'] ) || isset( $query['value'] );
1057         }
1058
1059         /**
1060          * Constructs a meta query based on 'meta_*' query vars
1061          *
1062          * @since 3.2.0
1063          * @access public
1064          *
1065          * @param array $qv The query variables
1066          */
1067         public function parse_query_vars( $qv ) {
1068                 $meta_query = array();
1069
1070                 /*
1071                  * For orderby=meta_value to work correctly, simple query needs to be
1072                  * first (so that its table join is against an unaliased meta table) and
1073                  * needs to be its own clause (so it doesn't interfere with the logic of
1074                  * the rest of the meta_query).
1075                  */
1076                 $primary_meta_query = array();
1077                 foreach ( array( 'key', 'compare', 'type' ) as $key ) {
1078                         if ( ! empty( $qv[ "meta_$key" ] ) ) {
1079                                 $primary_meta_query[ $key ] = $qv[ "meta_$key" ];
1080                         }
1081                 }
1082
1083                 // WP_Query sets 'meta_value' = '' by default.
1084                 if ( isset( $qv['meta_value'] ) && '' !== $qv['meta_value'] && ( ! is_array( $qv['meta_value'] ) || $qv['meta_value'] ) ) {
1085                         $primary_meta_query['value'] = $qv['meta_value'];
1086                 }
1087
1088                 $existing_meta_query = isset( $qv['meta_query'] ) && is_array( $qv['meta_query'] ) ? $qv['meta_query'] : array();
1089
1090                 if ( ! empty( $primary_meta_query ) && ! empty( $existing_meta_query ) ) {
1091                         $meta_query = array(
1092                                 'relation' => 'AND',
1093                                 $primary_meta_query,
1094                                 $existing_meta_query,
1095                         );
1096                 } else if ( ! empty( $primary_meta_query ) ) {
1097                         $meta_query = array(
1098                                 $primary_meta_query,
1099                         );
1100                 } else if ( ! empty( $existing_meta_query ) ) {
1101                         $meta_query = $existing_meta_query;
1102                 }
1103
1104                 $this->__construct( $meta_query );
1105         }
1106
1107         /**
1108          * Return the appropriate alias for the given meta type if applicable.
1109          *
1110          * @since 3.7.0
1111          * @access public
1112          *
1113          * @param string $type MySQL type to cast meta_value.
1114          * @return string MySQL type.
1115          */
1116         public function get_cast_for_type( $type = '' ) {
1117                 if ( empty( $type ) )
1118                         return 'CHAR';
1119
1120                 $meta_type = strtoupper( $type );
1121
1122                 if ( ! preg_match( '/^(?:BINARY|CHAR|DATE|DATETIME|SIGNED|UNSIGNED|TIME|NUMERIC(?:\(\d+(?:,\s?\d+)?\))?|DECIMAL(?:\(\d+(?:,\s?\d+)?\))?)$/', $meta_type ) )
1123                         return 'CHAR';
1124
1125                 if ( 'NUMERIC' == $meta_type )
1126                         $meta_type = 'SIGNED';
1127
1128                 return $meta_type;
1129         }
1130
1131         /**
1132          * Generates SQL clauses to be appended to a main query.
1133          *
1134          * @since 3.2.0
1135          * @access public
1136          *
1137          * @param string $type              Type of meta, eg 'user', 'post'.
1138          * @param string $primary_table     Database table where the object being filtered is stored (eg wp_users).
1139          * @param string $primary_id_column ID column for the filtered object in $primary_table.
1140          * @param object $context           Optional. The main query object.
1141          * @return array {
1142          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1143          *
1144          *     @type string $join  SQL fragment to append to the main JOIN clause.
1145          *     @type string $where SQL fragment to append to the main WHERE clause.
1146          * }
1147          */
1148         public function get_sql( $type, $primary_table, $primary_id_column, $context = null ) {
1149                 global $wpdb;
1150
1151                 if ( ! $meta_table = _get_meta_table( $type ) ) {
1152                         return false;
1153                 }
1154
1155                 $this->meta_table     = $meta_table;
1156                 $this->meta_id_column = sanitize_key( $type . '_id' );
1157
1158                 $this->primary_table     = $primary_table;
1159                 $this->primary_id_column = $primary_id_column;
1160
1161                 $sql = $this->get_sql_clauses();
1162
1163                 /*
1164                  * If any JOINs are LEFT JOINs (as in the case of NOT EXISTS), then all JOINs should
1165                  * be LEFT. Otherwise posts with no metadata will be excluded from results.
1166                  */
1167                 if ( false !== strpos( $sql['join'], 'LEFT JOIN' ) ) {
1168                         $sql['join'] = str_replace( 'INNER JOIN', 'LEFT JOIN', $sql['join'] );
1169                 }
1170
1171                 /**
1172                  * Filter the meta query's generated SQL.
1173                  *
1174                  * @since 3.1.0
1175                  *
1176                  * @param array $args {
1177                  *     An array of meta query SQL arguments.
1178                  *
1179                  *     @type array  $clauses           Array containing the query's JOIN and WHERE clauses.
1180                  *     @type array  $queries           Array of meta queries.
1181                  *     @type string $type              Type of meta.
1182                  *     @type string $primary_table     Primary table.
1183                  *     @type string $primary_id_column Primary column ID.
1184                  *     @type object $context           The main query object.
1185                  * }
1186                  */
1187                 return apply_filters_ref_array( 'get_meta_sql', array( $sql, $this->queries, $type, $primary_table, $primary_id_column, $context ) );
1188         }
1189
1190         /**
1191          * Generate SQL clauses to be appended to a main query.
1192          *
1193          * Called by the public {@see WP_Meta_Query::get_sql()}, this method
1194          * is abstracted out to maintain parity with the other Query classes.
1195          *
1196          * @since 4.1.0
1197          * @access protected
1198          *
1199          * @return array {
1200          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1201          *
1202          *     @type string $join  SQL fragment to append to the main JOIN clause.
1203          *     @type string $where SQL fragment to append to the main WHERE clause.
1204          * }
1205          */
1206         protected function get_sql_clauses() {
1207                 /*
1208                  * $queries are passed by reference to get_sql_for_query() for recursion.
1209                  * To keep $this->queries unaltered, pass a copy.
1210                  */
1211                 $queries = $this->queries;
1212                 $sql = $this->get_sql_for_query( $queries );
1213
1214                 if ( ! empty( $sql['where'] ) ) {
1215                         $sql['where'] = ' AND ' . $sql['where'];
1216                 }
1217
1218                 return $sql;
1219         }
1220
1221         /**
1222          * Generate SQL clauses for a single query array.
1223          *
1224          * If nested subqueries are found, this method recurses the tree to
1225          * produce the properly nested SQL.
1226          *
1227          * @since 4.1.0
1228          * @access protected
1229          *
1230          * @param array $query Query to parse, passed by reference.
1231          * @param int   $depth Optional. Number of tree levels deep we currently are.
1232          *                     Used to calculate indentation. Default 0.
1233          * @return array {
1234          *     Array containing JOIN and WHERE SQL clauses to append to a single query array.
1235          *
1236          *     @type string $join  SQL fragment to append to the main JOIN clause.
1237          *     @type string $where SQL fragment to append to the main WHERE clause.
1238          * }
1239          */
1240         protected function get_sql_for_query( &$query, $depth = 0 ) {
1241                 $sql_chunks = array(
1242                         'join'  => array(),
1243                         'where' => array(),
1244                 );
1245
1246                 $sql = array(
1247                         'join'  => '',
1248                         'where' => '',
1249                 );
1250
1251                 $indent = '';
1252                 for ( $i = 0; $i < $depth; $i++ ) {
1253                         $indent .= "  ";
1254                 }
1255
1256                 foreach ( $query as $key => &$clause ) {
1257                         if ( 'relation' === $key ) {
1258                                 $relation = $query['relation'];
1259                         } else if ( is_array( $clause ) ) {
1260
1261                                 // This is a first-order clause.
1262                                 if ( $this->is_first_order_clause( $clause ) ) {
1263                                         $clause_sql = $this->get_sql_for_clause( $clause, $query );
1264
1265                                         $where_count = count( $clause_sql['where'] );
1266                                         if ( ! $where_count ) {
1267                                                 $sql_chunks['where'][] = '';
1268                                         } else if ( 1 === $where_count ) {
1269                                                 $sql_chunks['where'][] = $clause_sql['where'][0];
1270                                         } else {
1271                                                 $sql_chunks['where'][] = '( ' . implode( ' AND ', $clause_sql['where'] ) . ' )';
1272                                         }
1273
1274                                         $sql_chunks['join'] = array_merge( $sql_chunks['join'], $clause_sql['join'] );
1275                                 // This is a subquery, so we recurse.
1276                                 } else {
1277                                         $clause_sql = $this->get_sql_for_query( $clause, $depth + 1 );
1278
1279                                         $sql_chunks['where'][] = $clause_sql['where'];
1280                                         $sql_chunks['join'][]  = $clause_sql['join'];
1281                                 }
1282                         }
1283                 }
1284
1285                 // Filter to remove empties.
1286                 $sql_chunks['join']  = array_filter( $sql_chunks['join'] );
1287                 $sql_chunks['where'] = array_filter( $sql_chunks['where'] );
1288
1289                 if ( empty( $relation ) ) {
1290                         $relation = 'AND';
1291                 }
1292
1293                 // Filter duplicate JOIN clauses and combine into a single string.
1294                 if ( ! empty( $sql_chunks['join'] ) ) {
1295                         $sql['join'] = implode( ' ', array_unique( $sql_chunks['join'] ) );
1296                 }
1297
1298                 // Generate a single WHERE clause with proper brackets and indentation.
1299                 if ( ! empty( $sql_chunks['where'] ) ) {
1300                         $sql['where'] = '( ' . "\n  " . $indent . implode( ' ' . "\n  " . $indent . $relation . ' ' . "\n  " . $indent, $sql_chunks['where'] ) . "\n" . $indent . ')';
1301                 }
1302
1303                 return $sql;
1304         }
1305
1306         /**
1307          * Generate SQL JOIN and WHERE clauses for a first-order query clause.
1308          *
1309          * "First-order" means that it's an array with a 'key' or 'value'.
1310          *
1311          * @since 4.1.0
1312          * @access public
1313          *
1314          * @param array $clause       Query clause, passed by reference.
1315          * @param array $parent_query Parent query array.
1316          * @return array {
1317          *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
1318          *
1319          *     @type string $join  SQL fragment to append to the main JOIN clause.
1320          *     @type string $where SQL fragment to append to the main WHERE clause.
1321          * }
1322          */
1323         public function get_sql_for_clause( &$clause, $parent_query ) {
1324                 global $wpdb;
1325
1326                 $sql_chunks = array(
1327                         'where' => array(),
1328                         'join' => array(),
1329                 );
1330
1331                 if ( isset( $clause['compare'] ) ) {
1332                         $clause['compare'] = strtoupper( $clause['compare'] );
1333                 } else {
1334                         $clause['compare'] = isset( $clause['value'] ) && is_array( $clause['value'] ) ? 'IN' : '=';
1335                 }
1336
1337                 if ( ! in_array( $clause['compare'], array(
1338                         '=', '!=', '>', '>=', '<', '<=',
1339                         'LIKE', 'NOT LIKE',
1340                         'IN', 'NOT IN',
1341                         'BETWEEN', 'NOT BETWEEN',
1342                         'EXISTS', 'NOT EXISTS',
1343                         'REGEXP', 'NOT REGEXP', 'RLIKE'
1344                 ) ) ) {
1345                         $clause['compare'] = '=';
1346                 }
1347
1348                 $meta_compare = $clause['compare'];
1349
1350                 // First build the JOIN clause, if one is required.
1351                 $join = '';
1352
1353                 // We prefer to avoid joins if possible. Look for an existing join compatible with this clause.
1354                 $alias = $this->find_compatible_table_alias( $clause, $parent_query );
1355                 if ( false === $alias ) {
1356                         $i = count( $this->table_aliases );
1357                         $alias = $i ? 'mt' . $i : $this->meta_table;
1358
1359                         // JOIN clauses for NOT EXISTS have their own syntax.
1360                         if ( 'NOT EXISTS' === $meta_compare ) {
1361                                 $join .= " LEFT JOIN $this->meta_table";
1362                                 $join .= $i ? " AS $alias" : '';
1363                                 $join .= $wpdb->prepare( " ON ($this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column AND $alias.meta_key = %s )", $clause['key'] );
1364
1365                         // All other JOIN clauses.
1366                         } else {
1367                                 $join .= " INNER JOIN $this->meta_table";
1368                                 $join .= $i ? " AS $alias" : '';
1369                                 $join .= " ON ( $this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column )";
1370                         }
1371
1372                         $this->table_aliases[] = $alias;
1373                         $sql_chunks['join'][] = $join;
1374                 }
1375
1376                 // Save the alias to this clause, for future siblings to find.
1377                 $clause['alias'] = $alias;
1378
1379                 // Next, build the WHERE clause.
1380
1381                 // meta_key.
1382                 if ( array_key_exists( 'key', $clause ) ) {
1383                         if ( 'NOT EXISTS' === $meta_compare ) {
1384                                 $sql_chunks['where'][] = $alias . '.' . $this->meta_id_column . ' IS NULL';
1385                         } else {
1386                                 $sql_chunks['where'][] = $wpdb->prepare( "$alias.meta_key = %s", trim( $clause['key'] ) );
1387                         }
1388                 }
1389
1390                 // meta_value.
1391                 if ( array_key_exists( 'value', $clause ) ) {
1392                         $meta_value = $clause['value'];
1393                         $meta_type = $this->get_cast_for_type( isset( $clause['type'] ) ? $clause['type'] : '' );
1394
1395                         if ( in_array( $meta_compare, array( 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN' ) ) ) {
1396                                 if ( ! is_array( $meta_value ) ) {
1397                                         $meta_value = preg_split( '/[,\s]+/', $meta_value );
1398                                 }
1399                         } else {
1400                                 $meta_value = trim( $meta_value );
1401                         }
1402
1403                         switch ( $meta_compare ) {
1404                                 case 'IN' :
1405                                 case 'NOT IN' :
1406                                         $meta_compare_string = '(' . substr( str_repeat( ',%s', count( $meta_value ) ), 1 ) . ')';
1407                                         $where = $wpdb->prepare( $meta_compare_string, $meta_value );
1408                                         break;
1409
1410                                 case 'BETWEEN' :
1411                                 case 'NOT BETWEEN' :
1412                                         $meta_value = array_slice( $meta_value, 0, 2 );
1413                                         $where = $wpdb->prepare( '%s AND %s', $meta_value );
1414                                         break;
1415
1416                                 case 'LIKE' :
1417                                 case 'NOT LIKE' :
1418                                         $meta_value = '%' . $wpdb->esc_like( $meta_value ) . '%';
1419                                         $where = $wpdb->prepare( '%s', $meta_value );
1420                                         break;
1421
1422                                 // EXISTS with a value is interpreted as '='.
1423                                 case 'EXISTS' :
1424                                         $meta_compare = '=';
1425                                         $where = $wpdb->prepare( '%s', $meta_value );
1426                                         break;
1427
1428                                 // 'value' is ignored for NOT EXISTS.
1429                                 case 'NOT EXISTS' :
1430                                         $where = '';
1431                                         break;
1432
1433                                 default :
1434                                         $where = $wpdb->prepare( '%s', $meta_value );
1435                                         break;
1436
1437                         }
1438
1439                         if ( $where ) {
1440                                 $sql_chunks['where'][] = "CAST($alias.meta_value AS {$meta_type}) {$meta_compare} {$where}";
1441                         }
1442                 }
1443
1444                 /*
1445                  * Multiple WHERE clauses (for meta_key and meta_value) should
1446                  * be joined in parentheses.
1447                  */
1448                 if ( 1 < count( $sql_chunks['where'] ) ) {
1449                         $sql_chunks['where'] = array( '( ' . implode( ' AND ', $sql_chunks['where'] ) . ' )' );
1450                 }
1451
1452                 return $sql_chunks;
1453         }
1454
1455         /**
1456          * Identify an existing table alias that is compatible with the current
1457          * query clause.
1458          *
1459          * We avoid unnecessary table joins by allowing each clause to look for
1460          * an existing table alias that is compatible with the query that it
1461          * needs to perform.
1462          *
1463          * An existing alias is compatible if (a) it is a sibling of `$clause`
1464          * (ie, it's under the scope of the same relation), and (b) the combination
1465          * of operator and relation between the clauses allows for a shared table join.
1466          * In the case of {@see WP_Meta_Query}, this only applies to 'IN' clauses that
1467          * are connected by the relation 'OR'.
1468          *
1469          * @since 4.1.0
1470          * @access protected
1471          *
1472          * @param  array       $clause       Query clause.
1473          * @param  array       $parent_query Parent query of $clause.
1474          * @return string|bool Table alias if found, otherwise false.
1475          */
1476         protected function find_compatible_table_alias( $clause, $parent_query ) {
1477                 $alias = false;
1478
1479                 foreach ( $parent_query as $sibling ) {
1480                         // If the sibling has no alias yet, there's nothing to check.
1481                         if ( empty( $sibling['alias'] ) ) {
1482                                 continue;
1483                         }
1484
1485                         // We're only interested in siblings that are first-order clauses.
1486                         if ( ! is_array( $sibling ) || ! $this->is_first_order_clause( $sibling ) ) {
1487                                 continue;
1488                         }
1489
1490                         $compatible_compares = array();
1491
1492                         // Clauses connected by OR can share joins as long as they have "positive" operators.
1493                         if ( 'OR' === $parent_query['relation'] ) {
1494                                 $compatible_compares = array( '=', 'IN', 'BETWEEN', 'LIKE', 'REGEXP', 'RLIKE', '>', '>=', '<', '<=' );
1495
1496                         // Clauses joined by AND with "negative" operators share a join only if they also share a key.
1497                         } else if ( isset( $sibling['key'] ) && isset( $clause['key'] ) && $sibling['key'] === $clause['key'] ) {
1498                                 $compatible_compares = array( '!=', 'NOT IN', 'NOT LIKE' );
1499                         }
1500
1501                         $clause_compare  = strtoupper( $clause['compare'] );
1502                         $sibling_compare = strtoupper( $sibling['compare'] );
1503                         if ( in_array( $clause_compare, $compatible_compares ) && in_array( $sibling_compare, $compatible_compares ) ) {
1504                                 $alias = $sibling['alias'];
1505                                 break;
1506                         }
1507                 }
1508
1509                 /**
1510                  * Filter the table alias identified as compatible with the current clause.
1511                  *
1512                  * @since 4.1.0
1513                  *
1514                  * @param string|bool $alias        Table alias, or false if none was found.
1515                  * @param array       $clause       First-order query clause.
1516                  * @param array       $parent_query Parent of $clause.
1517                  * @param object      $this         WP_Meta_Query object.
1518                  */
1519                 return apply_filters( 'meta_query_find_compatible_table_alias', $alias, $clause, $parent_query, $this ) ;
1520         }
1521 }
1522
1523 /**
1524  * Retrieve the name of the metadata table for the specified object type.
1525  *
1526  * @since 2.9.0
1527  *
1528  * @global wpdb $wpdb WordPress database abstraction object.
1529  *
1530  * @param string $type Type of object to get metadata table for (e.g., comment, post, or user)
1531  * @return mixed Metadata table name, or false if no metadata table exists
1532  */
1533 function _get_meta_table($type) {
1534         global $wpdb;
1535
1536         $table_name = $type . 'meta';
1537
1538         if ( empty($wpdb->$table_name) )
1539                 return false;
1540
1541         return $wpdb->$table_name;
1542 }
1543
1544 /**
1545  * Determine whether a meta key is protected.
1546  *
1547  * @since 3.1.3
1548  *
1549  * @param string      $meta_key Meta key
1550  * @param string|null $meta_type
1551  * @return bool True if the key is protected, false otherwise.
1552  */
1553 function is_protected_meta( $meta_key, $meta_type = null ) {
1554         $protected = ( '_' == $meta_key[0] );
1555
1556         /**
1557          * Filter whether a meta key is protected.
1558          *
1559          * @since 3.2.0
1560          *
1561          * @param bool   $protected Whether the key is protected. Default false.
1562          * @param string $meta_key  Meta key.
1563          * @param string $meta_type Meta type.
1564          */
1565         return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
1566 }
1567
1568 /**
1569  * Sanitize meta value.
1570  *
1571  * @since 3.1.3
1572  *
1573  * @param string $meta_key Meta key
1574  * @param mixed $meta_value Meta value to sanitize
1575  * @param string $meta_type Type of meta
1576  * @return mixed Sanitized $meta_value
1577  */
1578 function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
1579
1580         /**
1581          * Filter the sanitization of a specific meta key of a specific meta type.
1582          *
1583          * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
1584          * refer to the metadata object type (comment, post, or user) and the meta
1585          * key value,
1586          * respectively.
1587          *
1588          * @since 3.3.0
1589          *
1590          * @param mixed  $meta_value Meta value to sanitize.
1591          * @param string $meta_key   Meta key.
1592          * @param string $meta_type  Meta type.
1593          */
1594         return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
1595 }
1596
1597 /**
1598  * Register meta key
1599  *
1600  * @since 3.3.0
1601  *
1602  * @param string $meta_type Type of meta
1603  * @param string $meta_key Meta key
1604  * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
1605  * @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.
1606  */
1607 function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
1608         if ( is_callable( $sanitize_callback ) )
1609                 add_filter( "sanitize_{$meta_type}_meta_{$meta_key}", $sanitize_callback, 10, 3 );
1610
1611         if ( empty( $auth_callback ) ) {
1612                 if ( is_protected_meta( $meta_key, $meta_type ) )
1613                         $auth_callback = '__return_false';
1614                 else
1615                         $auth_callback = '__return_true';
1616         }
1617
1618         if ( is_callable( $auth_callback ) )
1619                 add_filter( "auth_{$meta_type}_meta_{$meta_key}", $auth_callback, 10, 6 );
1620 }