Another attempt to fix the http blog redirects.
[WebKit-https.git] / Websites / webkit.org / blog / 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 mixed 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          * A flat list of clauses, keyed by clause 'name'.
938          *
939          * @since 4.2.0
940          * @access protected
941          * @var array
942          */
943         protected $clauses = array();
944
945         /**
946          * Constructor.
947          *
948          * @since 3.2.0
949          * @since 4.2.0 Introduced support for naming query clauses by associative array keys.
950          *
951          * @access public
952          *
953          * @param array $meta_query {
954          *     Array of meta query clauses. When first-order clauses use strings as their array keys, they may be
955          *     referenced in the 'orderby' parameter of the parent query.
956          *
957          *     @type string $relation Optional. The MySQL keyword used to join
958          *                            the clauses of the query. Accepts 'AND', or 'OR'. Default 'AND'.
959          *     @type array {
960          *         Optional. An array of first-order clause parameters, or another fully-formed meta query.
961          *
962          *         @type string $key     Meta key to filter by.
963          *         @type string $value   Meta value to filter by.
964          *         @type string $compare MySQL operator used for comparing the $value. Accepts '=',
965          *                               '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN',
966          *                               'BETWEEN', 'NOT BETWEEN', 'REGEXP', 'NOT REGEXP', or 'RLIKE'.
967          *                               Default is 'IN' when `$value` is an array, '=' otherwise.
968          *         @type string $type    MySQL data type that the meta_value column will be CAST to for
969          *                               comparisons. Accepts 'NUMERIC', 'BINARY', 'CHAR', 'DATE',
970          *                               'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', or 'UNSIGNED'.
971          *                               Default is 'CHAR'.
972          *     }
973          * }
974          */
975         public function __construct( $meta_query = false ) {
976                 if ( !$meta_query )
977                         return;
978
979                 if ( isset( $meta_query['relation'] ) && strtoupper( $meta_query['relation'] ) == 'OR' ) {
980                         $this->relation = 'OR';
981                 } else {
982                         $this->relation = 'AND';
983                 }
984
985                 $this->queries = $this->sanitize_query( $meta_query );
986         }
987
988         /**
989          * Ensure the 'meta_query' argument passed to the class constructor is well-formed.
990          *
991          * Eliminates empty items and ensures that a 'relation' is set.
992          *
993          * @since 4.1.0
994          * @access public
995          *
996          * @param array $queries Array of query clauses.
997          * @return array Sanitized array of query clauses.
998          */
999         public function sanitize_query( $queries ) {
1000                 $clean_queries = array();
1001
1002                 if ( ! is_array( $queries ) ) {
1003                         return $clean_queries;
1004                 }
1005
1006                 foreach ( $queries as $key => $query ) {
1007                         if ( 'relation' === $key ) {
1008                                 $relation = $query;
1009
1010                         } elseif ( ! is_array( $query ) ) {
1011                                 continue;
1012
1013                         // First-order clause.
1014                         } elseif ( $this->is_first_order_clause( $query ) ) {
1015                                 if ( isset( $query['value'] ) && array() === $query['value'] ) {
1016                                         unset( $query['value'] );
1017                                 }
1018
1019                                 $clean_queries[ $key ] = $query;
1020
1021                         // Otherwise, it's a nested query, so we recurse.
1022                         } else {
1023                                 $cleaned_query = $this->sanitize_query( $query );
1024
1025                                 if ( ! empty( $cleaned_query ) ) {
1026                                         $clean_queries[ $key ] = $cleaned_query;
1027                                 }
1028                         }
1029                 }
1030
1031                 if ( empty( $clean_queries ) ) {
1032                         return $clean_queries;
1033                 }
1034
1035                 // Sanitize the 'relation' key provided in the query.
1036                 if ( isset( $relation ) && 'OR' === strtoupper( $relation ) ) {
1037                         $clean_queries['relation'] = 'OR';
1038
1039                 /*
1040                  * If there is only a single clause, call the relation 'OR'.
1041                  * This value will not actually be used to join clauses, but it
1042                  * simplifies the logic around combining key-only queries.
1043                  */
1044                 } elseif ( 1 === count( $clean_queries ) ) {
1045                         $clean_queries['relation'] = 'OR';
1046
1047                 // Default to AND.
1048                 } else {
1049                         $clean_queries['relation'] = 'AND';
1050                 }
1051
1052                 return $clean_queries;
1053         }
1054
1055         /**
1056          * Determine whether a query clause is first-order.
1057          *
1058          * A first-order meta query clause is one that has either a 'key' or
1059          * a 'value' array key.
1060          *
1061          * @since 4.1.0
1062          * @access protected
1063          *
1064          * @param array $query Meta query arguments.
1065          * @return bool Whether the query clause is a first-order clause.
1066          */
1067         protected function is_first_order_clause( $query ) {
1068                 return isset( $query['key'] ) || isset( $query['value'] );
1069         }
1070
1071         /**
1072          * Constructs a meta query based on 'meta_*' query vars
1073          *
1074          * @since 3.2.0
1075          * @access public
1076          *
1077          * @param array $qv The query variables
1078          */
1079         public function parse_query_vars( $qv ) {
1080                 $meta_query = array();
1081
1082                 /*
1083                  * For orderby=meta_value to work correctly, simple query needs to be
1084                  * first (so that its table join is against an unaliased meta table) and
1085                  * needs to be its own clause (so it doesn't interfere with the logic of
1086                  * the rest of the meta_query).
1087                  */
1088                 $primary_meta_query = array();
1089                 foreach ( array( 'key', 'compare', 'type' ) as $key ) {
1090                         if ( ! empty( $qv[ "meta_$key" ] ) ) {
1091                                 $primary_meta_query[ $key ] = $qv[ "meta_$key" ];
1092                         }
1093                 }
1094
1095                 // WP_Query sets 'meta_value' = '' by default.
1096                 if ( isset( $qv['meta_value'] ) && '' !== $qv['meta_value'] && ( ! is_array( $qv['meta_value'] ) || $qv['meta_value'] ) ) {
1097                         $primary_meta_query['value'] = $qv['meta_value'];
1098                 }
1099
1100                 $existing_meta_query = isset( $qv['meta_query'] ) && is_array( $qv['meta_query'] ) ? $qv['meta_query'] : array();
1101
1102                 if ( ! empty( $primary_meta_query ) && ! empty( $existing_meta_query ) ) {
1103                         $meta_query = array(
1104                                 'relation' => 'AND',
1105                                 $primary_meta_query,
1106                                 $existing_meta_query,
1107                         );
1108                 } elseif ( ! empty( $primary_meta_query ) ) {
1109                         $meta_query = array(
1110                                 $primary_meta_query,
1111                         );
1112                 } elseif ( ! empty( $existing_meta_query ) ) {
1113                         $meta_query = $existing_meta_query;
1114                 }
1115
1116                 $this->__construct( $meta_query );
1117         }
1118
1119         /**
1120          * Return the appropriate alias for the given meta type if applicable.
1121          *
1122          * @since 3.7.0
1123          * @access public
1124          *
1125          * @param string $type MySQL type to cast meta_value.
1126          * @return string MySQL type.
1127          */
1128         public function get_cast_for_type( $type = '' ) {
1129                 if ( empty( $type ) )
1130                         return 'CHAR';
1131
1132                 $meta_type = strtoupper( $type );
1133
1134                 if ( ! preg_match( '/^(?:BINARY|CHAR|DATE|DATETIME|SIGNED|UNSIGNED|TIME|NUMERIC(?:\(\d+(?:,\s?\d+)?\))?|DECIMAL(?:\(\d+(?:,\s?\d+)?\))?)$/', $meta_type ) )
1135                         return 'CHAR';
1136
1137                 if ( 'NUMERIC' == $meta_type )
1138                         $meta_type = 'SIGNED';
1139
1140                 return $meta_type;
1141         }
1142
1143         /**
1144          * Generates SQL clauses to be appended to a main query.
1145          *
1146          * @since 3.2.0
1147          * @access public
1148          *
1149          * @param string $type              Type of meta, eg 'user', 'post'.
1150          * @param string $primary_table     Database table where the object being filtered is stored (eg wp_users).
1151          * @param string $primary_id_column ID column for the filtered object in $primary_table.
1152          * @param object $context           Optional. The main query object.
1153          * @return array {
1154          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1155          *
1156          *     @type string $join  SQL fragment to append to the main JOIN clause.
1157          *     @type string $where SQL fragment to append to the main WHERE clause.
1158          * }
1159          */
1160         public function get_sql( $type, $primary_table, $primary_id_column, $context = null ) {
1161                 if ( ! $meta_table = _get_meta_table( $type ) ) {
1162                         return false;
1163                 }
1164
1165                 $this->meta_table     = $meta_table;
1166                 $this->meta_id_column = sanitize_key( $type . '_id' );
1167
1168                 $this->primary_table     = $primary_table;
1169                 $this->primary_id_column = $primary_id_column;
1170
1171                 $sql = $this->get_sql_clauses();
1172
1173                 /*
1174                  * If any JOINs are LEFT JOINs (as in the case of NOT EXISTS), then all JOINs should
1175                  * be LEFT. Otherwise posts with no metadata will be excluded from results.
1176                  */
1177                 if ( false !== strpos( $sql['join'], 'LEFT JOIN' ) ) {
1178                         $sql['join'] = str_replace( 'INNER JOIN', 'LEFT JOIN', $sql['join'] );
1179                 }
1180
1181                 /**
1182                  * Filter the meta query's generated SQL.
1183                  *
1184                  * @since 3.1.0
1185                  *
1186                  * @param array $args {
1187                  *     An array of meta query SQL arguments.
1188                  *
1189                  *     @type array  $clauses           Array containing the query's JOIN and WHERE clauses.
1190                  *     @type array  $queries           Array of meta queries.
1191                  *     @type string $type              Type of meta.
1192                  *     @type string $primary_table     Primary table.
1193                  *     @type string $primary_id_column Primary column ID.
1194                  *     @type object $context           The main query object.
1195                  * }
1196                  */
1197                 return apply_filters_ref_array( 'get_meta_sql', array( $sql, $this->queries, $type, $primary_table, $primary_id_column, $context ) );
1198         }
1199
1200         /**
1201          * Generate SQL clauses to be appended to a main query.
1202          *
1203          * Called by the public {@see WP_Meta_Query::get_sql()}, this method
1204          * is abstracted out to maintain parity with the other Query classes.
1205          *
1206          * @since 4.1.0
1207          * @access protected
1208          *
1209          * @return array {
1210          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1211          *
1212          *     @type string $join  SQL fragment to append to the main JOIN clause.
1213          *     @type string $where SQL fragment to append to the main WHERE clause.
1214          * }
1215          */
1216         protected function get_sql_clauses() {
1217                 /*
1218                  * $queries are passed by reference to get_sql_for_query() for recursion.
1219                  * To keep $this->queries unaltered, pass a copy.
1220                  */
1221                 $queries = $this->queries;
1222                 $sql = $this->get_sql_for_query( $queries );
1223
1224                 if ( ! empty( $sql['where'] ) ) {
1225                         $sql['where'] = ' AND ' . $sql['where'];
1226                 }
1227
1228                 return $sql;
1229         }
1230
1231         /**
1232          * Generate SQL clauses for a single query array.
1233          *
1234          * If nested subqueries are found, this method recurses the tree to
1235          * produce the properly nested SQL.
1236          *
1237          * @since 4.1.0
1238          * @access protected
1239          *
1240          * @param array $query Query to parse, passed by reference.
1241          * @param int   $depth Optional. Number of tree levels deep we currently are.
1242          *                     Used to calculate indentation. Default 0.
1243          * @return array {
1244          *     Array containing JOIN and WHERE SQL clauses to append to a single query array.
1245          *
1246          *     @type string $join  SQL fragment to append to the main JOIN clause.
1247          *     @type string $where SQL fragment to append to the main WHERE clause.
1248          * }
1249          */
1250         protected function get_sql_for_query( &$query, $depth = 0 ) {
1251                 $sql_chunks = array(
1252                         'join'  => array(),
1253                         'where' => array(),
1254                 );
1255
1256                 $sql = array(
1257                         'join'  => '',
1258                         'where' => '',
1259                 );
1260
1261                 $indent = '';
1262                 for ( $i = 0; $i < $depth; $i++ ) {
1263                         $indent .= "  ";
1264                 }
1265
1266                 foreach ( $query as $key => &$clause ) {
1267                         if ( 'relation' === $key ) {
1268                                 $relation = $query['relation'];
1269                         } elseif ( is_array( $clause ) ) {
1270
1271                                 // This is a first-order clause.
1272                                 if ( $this->is_first_order_clause( $clause ) ) {
1273                                         $clause_sql = $this->get_sql_for_clause( $clause, $query, $key );
1274
1275                                         $where_count = count( $clause_sql['where'] );
1276                                         if ( ! $where_count ) {
1277                                                 $sql_chunks['where'][] = '';
1278                                         } elseif ( 1 === $where_count ) {
1279                                                 $sql_chunks['where'][] = $clause_sql['where'][0];
1280                                         } else {
1281                                                 $sql_chunks['where'][] = '( ' . implode( ' AND ', $clause_sql['where'] ) . ' )';
1282                                         }
1283
1284                                         $sql_chunks['join'] = array_merge( $sql_chunks['join'], $clause_sql['join'] );
1285                                 // This is a subquery, so we recurse.
1286                                 } else {
1287                                         $clause_sql = $this->get_sql_for_query( $clause, $depth + 1 );
1288
1289                                         $sql_chunks['where'][] = $clause_sql['where'];
1290                                         $sql_chunks['join'][]  = $clause_sql['join'];
1291                                 }
1292                         }
1293                 }
1294
1295                 // Filter to remove empties.
1296                 $sql_chunks['join']  = array_filter( $sql_chunks['join'] );
1297                 $sql_chunks['where'] = array_filter( $sql_chunks['where'] );
1298
1299                 if ( empty( $relation ) ) {
1300                         $relation = 'AND';
1301                 }
1302
1303                 // Filter duplicate JOIN clauses and combine into a single string.
1304                 if ( ! empty( $sql_chunks['join'] ) ) {
1305                         $sql['join'] = implode( ' ', array_unique( $sql_chunks['join'] ) );
1306                 }
1307
1308                 // Generate a single WHERE clause with proper brackets and indentation.
1309                 if ( ! empty( $sql_chunks['where'] ) ) {
1310                         $sql['where'] = '( ' . "\n  " . $indent . implode( ' ' . "\n  " . $indent . $relation . ' ' . "\n  " . $indent, $sql_chunks['where'] ) . "\n" . $indent . ')';
1311                 }
1312
1313                 return $sql;
1314         }
1315
1316         /**
1317          * Generate SQL JOIN and WHERE clauses for a first-order query clause.
1318          *
1319          * "First-order" means that it's an array with a 'key' or 'value'.
1320          *
1321          * @since 4.1.0
1322          * @access public
1323          *
1324          * @param array  $clause       Query clause, passed by reference.
1325          * @param array  $parent_query Parent query array.
1326          * @param string $clause_key   Optional. The array key used to name the clause in the original `$meta_query`
1327          *                             parameters. If not provided, a key will be generated automatically.
1328          * @return array {
1329          *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
1330          *
1331          *     @type string $join  SQL fragment to append to the main JOIN clause.
1332          *     @type string $where SQL fragment to append to the main WHERE clause.
1333          * }
1334          */
1335         public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) {
1336                 global $wpdb;
1337
1338                 $sql_chunks = array(
1339                         'where' => array(),
1340                         'join' => array(),
1341                 );
1342
1343                 if ( isset( $clause['compare'] ) ) {
1344                         $clause['compare'] = strtoupper( $clause['compare'] );
1345                 } else {
1346                         $clause['compare'] = isset( $clause['value'] ) && is_array( $clause['value'] ) ? 'IN' : '=';
1347                 }
1348
1349                 if ( ! in_array( $clause['compare'], array(
1350                         '=', '!=', '>', '>=', '<', '<=',
1351                         'LIKE', 'NOT LIKE',
1352                         'IN', 'NOT IN',
1353                         'BETWEEN', 'NOT BETWEEN',
1354                         'EXISTS', 'NOT EXISTS',
1355                         'REGEXP', 'NOT REGEXP', 'RLIKE'
1356                 ) ) ) {
1357                         $clause['compare'] = '=';
1358                 }
1359
1360                 $meta_compare = $clause['compare'];
1361
1362                 // First build the JOIN clause, if one is required.
1363                 $join = '';
1364
1365                 // We prefer to avoid joins if possible. Look for an existing join compatible with this clause.
1366                 $alias = $this->find_compatible_table_alias( $clause, $parent_query );
1367                 if ( false === $alias ) {
1368                         $i = count( $this->table_aliases );
1369                         $alias = $i ? 'mt' . $i : $this->meta_table;
1370
1371                         // JOIN clauses for NOT EXISTS have their own syntax.
1372                         if ( 'NOT EXISTS' === $meta_compare ) {
1373                                 $join .= " LEFT JOIN $this->meta_table";
1374                                 $join .= $i ? " AS $alias" : '';
1375                                 $join .= $wpdb->prepare( " ON ($this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column AND $alias.meta_key = %s )", $clause['key'] );
1376
1377                         // All other JOIN clauses.
1378                         } else {
1379                                 $join .= " INNER JOIN $this->meta_table";
1380                                 $join .= $i ? " AS $alias" : '';
1381                                 $join .= " ON ( $this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column )";
1382                         }
1383
1384                         $this->table_aliases[] = $alias;
1385                         $sql_chunks['join'][] = $join;
1386                 }
1387
1388                 // Save the alias to this clause, for future siblings to find.
1389                 $clause['alias'] = $alias;
1390
1391                 // Determine the data type.
1392                 $_meta_type = isset( $clause['type'] ) ? $clause['type'] : '';
1393                 $meta_type  = $this->get_cast_for_type( $_meta_type );
1394                 $clause['cast'] = $meta_type;
1395
1396                 // Fallback for clause keys is the table alias.
1397                 if ( ! $clause_key ) {
1398                         $clause_key = $clause['alias'];
1399                 }
1400
1401                 // Ensure unique clause keys, so none are overwritten.
1402                 $iterator = 1;
1403                 $clause_key_base = $clause_key;
1404                 while ( isset( $this->clauses[ $clause_key ] ) ) {
1405                         $clause_key = $clause_key_base . '-' . $iterator;
1406                         $iterator++;
1407                 }
1408
1409                 // Store the clause in our flat array.
1410                 $this->clauses[ $clause_key ] =& $clause;
1411
1412                 // Next, build the WHERE clause.
1413
1414                 // meta_key.
1415                 if ( array_key_exists( 'key', $clause ) ) {
1416                         if ( 'NOT EXISTS' === $meta_compare ) {
1417                                 $sql_chunks['where'][] = $alias . '.' . $this->meta_id_column . ' IS NULL';
1418                         } else {
1419                                 $sql_chunks['where'][] = $wpdb->prepare( "$alias.meta_key = %s", trim( $clause['key'] ) );
1420                         }
1421                 }
1422
1423                 // meta_value.
1424                 if ( array_key_exists( 'value', $clause ) ) {
1425                         $meta_value = $clause['value'];
1426
1427                         if ( in_array( $meta_compare, array( 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN' ) ) ) {
1428                                 if ( ! is_array( $meta_value ) ) {
1429                                         $meta_value = preg_split( '/[,\s]+/', $meta_value );
1430                                 }
1431                         } else {
1432                                 $meta_value = trim( $meta_value );
1433                         }
1434
1435                         switch ( $meta_compare ) {
1436                                 case 'IN' :
1437                                 case 'NOT IN' :
1438                                         $meta_compare_string = '(' . substr( str_repeat( ',%s', count( $meta_value ) ), 1 ) . ')';
1439                                         $where = $wpdb->prepare( $meta_compare_string, $meta_value );
1440                                         break;
1441
1442                                 case 'BETWEEN' :
1443                                 case 'NOT BETWEEN' :
1444                                         $meta_value = array_slice( $meta_value, 0, 2 );
1445                                         $where = $wpdb->prepare( '%s AND %s', $meta_value );
1446                                         break;
1447
1448                                 case 'LIKE' :
1449                                 case 'NOT LIKE' :
1450                                         $meta_value = '%' . $wpdb->esc_like( $meta_value ) . '%';
1451                                         $where = $wpdb->prepare( '%s', $meta_value );
1452                                         break;
1453
1454                                 // EXISTS with a value is interpreted as '='.
1455                                 case 'EXISTS' :
1456                                         $meta_compare = '=';
1457                                         $where = $wpdb->prepare( '%s', $meta_value );
1458                                         break;
1459
1460                                 // 'value' is ignored for NOT EXISTS.
1461                                 case 'NOT EXISTS' :
1462                                         $where = '';
1463                                         break;
1464
1465                                 default :
1466                                         $where = $wpdb->prepare( '%s', $meta_value );
1467                                         break;
1468
1469                         }
1470
1471                         if ( $where ) {
1472                                 $sql_chunks['where'][] = "CAST($alias.meta_value AS {$meta_type}) {$meta_compare} {$where}";
1473                         }
1474                 }
1475
1476                 /*
1477                  * Multiple WHERE clauses (for meta_key and meta_value) should
1478                  * be joined in parentheses.
1479                  */
1480                 if ( 1 < count( $sql_chunks['where'] ) ) {
1481                         $sql_chunks['where'] = array( '( ' . implode( ' AND ', $sql_chunks['where'] ) . ' )' );
1482                 }
1483
1484                 return $sql_chunks;
1485         }
1486
1487         /**
1488          * Get a flattened list of sanitized meta clauses.
1489          *
1490          * This array should be used for clause lookup, as when the table alias and CAST type must be determined for
1491          * a value of 'orderby' corresponding to a meta clause.
1492          *
1493          * @since 4.2.0
1494          * @access public
1495          *
1496          * @return array Meta clauses.
1497          */
1498         public function get_clauses() {
1499                 return $this->clauses;
1500         }
1501
1502         /**
1503          * Identify an existing table alias that is compatible with the current
1504          * query clause.
1505          *
1506          * We avoid unnecessary table joins by allowing each clause to look for
1507          * an existing table alias that is compatible with the query that it
1508          * needs to perform.
1509          *
1510          * An existing alias is compatible if (a) it is a sibling of `$clause`
1511          * (ie, it's under the scope of the same relation), and (b) the combination
1512          * of operator and relation between the clauses allows for a shared table join.
1513          * In the case of {@see WP_Meta_Query}, this only applies to 'IN' clauses that
1514          * are connected by the relation 'OR'.
1515          *
1516          * @since 4.1.0
1517          * @access protected
1518          *
1519          * @param  array       $clause       Query clause.
1520          * @param  array       $parent_query Parent query of $clause.
1521          * @return string|bool Table alias if found, otherwise false.
1522          */
1523         protected function find_compatible_table_alias( $clause, $parent_query ) {
1524                 $alias = false;
1525
1526                 foreach ( $parent_query as $sibling ) {
1527                         // If the sibling has no alias yet, there's nothing to check.
1528                         if ( empty( $sibling['alias'] ) ) {
1529                                 continue;
1530                         }
1531
1532                         // We're only interested in siblings that are first-order clauses.
1533                         if ( ! is_array( $sibling ) || ! $this->is_first_order_clause( $sibling ) ) {
1534                                 continue;
1535                         }
1536
1537                         $compatible_compares = array();
1538
1539                         // Clauses connected by OR can share joins as long as they have "positive" operators.
1540                         if ( 'OR' === $parent_query['relation'] ) {
1541                                 $compatible_compares = array( '=', 'IN', 'BETWEEN', 'LIKE', 'REGEXP', 'RLIKE', '>', '>=', '<', '<=' );
1542
1543                         // Clauses joined by AND with "negative" operators share a join only if they also share a key.
1544                         } elseif ( isset( $sibling['key'] ) && isset( $clause['key'] ) && $sibling['key'] === $clause['key'] ) {
1545                                 $compatible_compares = array( '!=', 'NOT IN', 'NOT LIKE' );
1546                         }
1547
1548                         $clause_compare  = strtoupper( $clause['compare'] );
1549                         $sibling_compare = strtoupper( $sibling['compare'] );
1550                         if ( in_array( $clause_compare, $compatible_compares ) && in_array( $sibling_compare, $compatible_compares ) ) {
1551                                 $alias = $sibling['alias'];
1552                                 break;
1553                         }
1554                 }
1555
1556                 /**
1557                  * Filter the table alias identified as compatible with the current clause.
1558                  *
1559                  * @since 4.1.0
1560                  *
1561                  * @param string|bool $alias        Table alias, or false if none was found.
1562                  * @param array       $clause       First-order query clause.
1563                  * @param array       $parent_query Parent of $clause.
1564                  * @param object      $this         WP_Meta_Query object.
1565                  */
1566                 return apply_filters( 'meta_query_find_compatible_table_alias', $alias, $clause, $parent_query, $this ) ;
1567         }
1568 }
1569
1570 /**
1571  * Retrieve the name of the metadata table for the specified object type.
1572  *
1573  * @since 2.9.0
1574  *
1575  * @global wpdb $wpdb WordPress database abstraction object.
1576  *
1577  * @param string $type Type of object to get metadata table for (e.g., comment, post, or user)
1578  * @return mixed Metadata table name, or false if no metadata table exists
1579  */
1580 function _get_meta_table($type) {
1581         global $wpdb;
1582
1583         $table_name = $type . 'meta';
1584
1585         if ( empty($wpdb->$table_name) )
1586                 return false;
1587
1588         return $wpdb->$table_name;
1589 }
1590
1591 /**
1592  * Determine whether a meta key is protected.
1593  *
1594  * @since 3.1.3
1595  *
1596  * @param string      $meta_key Meta key
1597  * @param string|null $meta_type
1598  * @return bool True if the key is protected, false otherwise.
1599  */
1600 function is_protected_meta( $meta_key, $meta_type = null ) {
1601         $protected = ( '_' == $meta_key[0] );
1602
1603         /**
1604          * Filter whether a meta key is protected.
1605          *
1606          * @since 3.2.0
1607          *
1608          * @param bool   $protected Whether the key is protected. Default false.
1609          * @param string $meta_key  Meta key.
1610          * @param string $meta_type Meta type.
1611          */
1612         return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
1613 }
1614
1615 /**
1616  * Sanitize meta value.
1617  *
1618  * @since 3.1.3
1619  *
1620  * @param string $meta_key Meta key
1621  * @param mixed $meta_value Meta value to sanitize
1622  * @param string $meta_type Type of meta
1623  * @return mixed Sanitized $meta_value
1624  */
1625 function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
1626
1627         /**
1628          * Filter the sanitization of a specific meta key of a specific meta type.
1629          *
1630          * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
1631          * refer to the metadata object type (comment, post, or user) and the meta
1632          * key value,
1633          * respectively.
1634          *
1635          * @since 3.3.0
1636          *
1637          * @param mixed  $meta_value Meta value to sanitize.
1638          * @param string $meta_key   Meta key.
1639          * @param string $meta_type  Meta type.
1640          */
1641         return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
1642 }
1643
1644 /**
1645  * Register meta key
1646  *
1647  * @since 3.3.0
1648  *
1649  * @param string $meta_type Type of meta
1650  * @param string $meta_key Meta key
1651  * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
1652  * @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.
1653  */
1654 function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
1655         if ( is_callable( $sanitize_callback ) )
1656                 add_filter( "sanitize_{$meta_type}_meta_{$meta_key}", $sanitize_callback, 10, 3 );
1657
1658         if ( empty( $auth_callback ) ) {
1659                 if ( is_protected_meta( $meta_key, $meta_type ) )
1660                         $auth_callback = '__return_false';
1661                 else
1662                         $auth_callback = '__return_true';
1663         }
1664
1665         if ( is_callable( $auth_callback ) )
1666                 add_filter( "auth_{$meta_type}_meta_{$meta_key}", $auth_callback, 10, 6 );
1667 }