| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Meta API: WP_Meta_Query class 4 * 5 * @package WordPress 6 * @subpackage Meta 7 * @since 4.4.0 8 */ 9 10 /** 11 * Core class used to implement meta queries for the Meta API. 12 * 13 * Used for generating SQL clauses that filter a primary query according to metadata keys and values. 14 * 15 * WP_Meta_Query is a helper that allows primary query classes, such as WP_Query and WP_User_Query, 16 * 17 * to filter their results by object metadata, by generating `JOIN` and `WHERE` subclauses to be attached 18 * to the primary SQL query string. 19 * 20 * @since 3.2.0 21 */ 22 class WP_Meta_Query { 23 /** 24 * Array of metadata queries. 25 * 26 * See WP_Meta_Query::__construct() for information on meta query arguments. 27 * 28 * @since 3.2.0 29 * @var array 30 */ 31 public $queries = array(); 32 33 /** 34 * The relation between the queries. Can be one of 'AND' or 'OR'. 35 * 36 * @since 3.2.0 37 * @var string 38 */ 39 public $relation; 40 41 /** 42 * Database table to query for the metadata. 43 * 44 * @since 4.1.0 45 * @var string 46 */ 47 public $meta_table; 48 49 /** 50 * Column in meta_table that represents the ID of the object the metadata belongs to. 51 * 52 * @since 4.1.0 53 * @var string 54 */ 55 public $meta_id_column; 56 57 /** 58 * Database table that where the metadata's objects are stored (eg $wpdb->users). 59 * 60 * @since 4.1.0 61 * @var string 62 */ 63 public $primary_table; 64 65 /** 66 * Column in primary_table that represents the ID of the object. 67 * 68 * @since 4.1.0 69 * @var string 70 */ 71 public $primary_id_column; 72 73 /** 74 * A flat list of table aliases used in JOIN clauses. 75 * 76 * @since 4.1.0 77 * @var array 78 */ 79 protected $table_aliases = array(); 80 81 /** 82 * A flat list of clauses, keyed by clause 'name'. 83 * 84 * @since 4.2.0 85 * @var array 86 */ 87 protected $clauses = array(); 88 89 /** 90 * Whether the query contains any OR relations. 91 * 92 * @since 4.3.0 93 * @var bool 94 */ 95 protected $has_or_relation = false; 96 97 /** 98 * Constructor. 99 * 100 * @since 3.2.0 101 * @since 4.2.0 Introduced support for naming query clauses by associative array keys. 102 * @since 5.1.0 Introduced $compare_key clause parameter, which enables LIKE key matches. 103 * @since 5.3.0 Increased the number of operators available to $compare_key. Introduced $type_key, 104 * which enables the $key to be cast to a new data type for comparisons. 105 * 106 * @param array $meta_query { 107 * Array of meta query clauses. When first-order clauses or sub-clauses use strings as 108 * their array keys, they may be referenced in the 'orderby' parameter of the parent query. 109 * 110 * @type string $relation Optional. The MySQL keyword used to join 111 * the clauses of the query. Accepts 'AND', or 'OR'. Default 'AND'. 112 * @type array ...$0 { 113 * Optional. An array of first-order clause parameters, or another fully-formed meta query. 114 * 115 * @type string $key Meta key to filter by. 116 * @type string $compare_key MySQL operator used for comparing the $key. Accepts '=', '!=' 117 * 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'REGEXP', 'NOT REGEXP', 'RLIKE', 118 * 'EXISTS' (alias of '=') or 'NOT EXISTS' (alias of '!='). 119 * Default is 'IN' when `$key` is an array, '=' otherwise. 120 * @type string $type_key MySQL data type that the meta_key column will be CAST to for 121 * comparisons. Accepts 'BINARY' for case-sensitive regular expression 122 * comparisons. Default is ''. 123 * @type string $value Meta value to filter by. 124 * @type string $compare MySQL operator used for comparing the $value. Accepts '=', 125 * '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 126 * 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'REGEXP', 127 * 'NOT REGEXP', 'RLIKE', 'EXISTS' or 'NOT EXISTS'. 128 * Default is 'IN' when `$value` is an array, '=' otherwise. 129 * @type string $type MySQL data type that the meta_value column will be CAST to for 130 * comparisons. Accepts 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 131 * 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', or 'UNSIGNED'. 132 * Default is 'CHAR'. 133 * } 134 * } 135 */ 136 public function __construct( $meta_query = false ) { 137 if ( ! $meta_query ) { 138 return; 139 } 140 141 if ( isset( $meta_query['relation'] ) && 'OR' === strtoupper( $meta_query['relation'] ) ) { 142 $this->relation = 'OR'; 143 } else { 144 $this->relation = 'AND'; 145 } 146 147 $this->queries = $this->sanitize_query( $meta_query ); 148 } 149 150 /** 151 * Ensure the 'meta_query' argument passed to the class constructor is well-formed. 152 * 153 * Eliminates empty items and ensures that a 'relation' is set. 154 * 155 * @since 4.1.0 156 * 157 * @param array $queries Array of query clauses. 158 * @return array Sanitized array of query clauses. 159 */ 160 public function sanitize_query( $queries ) { 161 $clean_queries = array(); 162 163 if ( ! is_array( $queries ) ) { 164 return $clean_queries; 165 } 166 167 foreach ( $queries as $key => $query ) { 168 if ( 'relation' === $key ) { 169 $relation = $query; 170 171 } elseif ( ! is_array( $query ) ) { 172 continue; 173 174 // First-order clause. 175 } elseif ( $this->is_first_order_clause( $query ) ) { 176 if ( isset( $query['value'] ) && array() === $query['value'] ) { 177 unset( $query['value'] ); 178 } 179 180 $clean_queries[ $key ] = $query; 181 182 // Otherwise, it's a nested query, so we recurse. 183 } else { 184 $cleaned_query = $this->sanitize_query( $query ); 185 186 if ( ! empty( $cleaned_query ) ) { 187 $clean_queries[ $key ] = $cleaned_query; 188 } 189 } 190 } 191 192 if ( empty( $clean_queries ) ) { 193 return $clean_queries; 194 } 195 196 // Sanitize the 'relation' key provided in the query. 197 if ( isset( $relation ) && 'OR' === strtoupper( $relation ) ) { 198 $clean_queries['relation'] = 'OR'; 199 $this->has_or_relation = true; 200 201 /* 202 * If there is only a single clause, call the relation 'OR'. 203 * This value will not actually be used to join clauses, but it 204 * simplifies the logic around combining key-only queries. 205 */ 206 } elseif ( 1 === count( $clean_queries ) ) { 207 $clean_queries['relation'] = 'OR'; 208 209 // Default to AND. 210 } else { 211 $clean_queries['relation'] = 'AND'; 212 } 213 214 return $clean_queries; 215 } 216 217 /** 218 * Determine whether a query clause is first-order. 219 * 220 * A first-order meta query clause is one that has either a 'key' or 221 * a 'value' array key. 222 * 223 * @since 4.1.0 224 * 225 * @param array $query Meta query arguments. 226 * @return bool Whether the query clause is a first-order clause. 227 */ 228 protected function is_first_order_clause( $query ) { 229 return isset( $query['key'] ) || isset( $query['value'] ); 230 } 231 232 /** 233 * Constructs a meta query based on 'meta_*' query vars 234 * 235 * @since 3.2.0 236 * 237 * @param array $qv The query variables 238 */ 239 public function parse_query_vars( $qv ) { 240 $meta_query = array(); 241 242 /* 243 * For orderby=meta_value to work correctly, simple query needs to be 244 * first (so that its table join is against an unaliased meta table) and 245 * needs to be its own clause (so it doesn't interfere with the logic of 246 * the rest of the meta_query). 247 */ 248 $primary_meta_query = array(); 249 foreach ( array( 'key', 'compare', 'type', 'compare_key', 'type_key' ) as $key ) { 250 if ( ! empty( $qv[ "meta_$key" ] ) ) { 251 $primary_meta_query[ $key ] = $qv[ "meta_$key" ]; 252 } 253 } 254 255 // WP_Query sets 'meta_value' = '' by default. 256 if ( isset( $qv['meta_value'] ) && '' !== $qv['meta_value'] && ( ! is_array( $qv['meta_value'] ) || $qv['meta_value'] ) ) { 257 $primary_meta_query['value'] = $qv['meta_value']; 258 } 259 260 $existing_meta_query = isset( $qv['meta_query'] ) && is_array( $qv['meta_query'] ) ? $qv['meta_query'] : array(); 261 262 if ( ! empty( $primary_meta_query ) && ! empty( $existing_meta_query ) ) { 263 $meta_query = array( 264 'relation' => 'AND', 265 $primary_meta_query, 266 $existing_meta_query, 267 ); 268 } elseif ( ! empty( $primary_meta_query ) ) { 269 $meta_query = array( 270 $primary_meta_query, 271 ); 272 } elseif ( ! empty( $existing_meta_query ) ) { 273 $meta_query = $existing_meta_query; 274 } 275 276 $this->__construct( $meta_query ); 277 } 278 279 /** 280 * Return the appropriate alias for the given meta type if applicable. 281 * 282 * @since 3.7.0 283 * 284 * @param string $type MySQL type to cast meta_value. 285 * @return string MySQL type. 286 */ 287 public function get_cast_for_type( $type = '' ) { 288 if ( empty( $type ) ) { 289 return 'CHAR'; 290 } 291 292 $meta_type = strtoupper( $type ); 293 294 if ( ! preg_match( '/^(?:BINARY|CHAR|DATE|DATETIME|SIGNED|UNSIGNED|TIME|NUMERIC(?:\(\d+(?:,\s?\d+)?\))?|DECIMAL(?:\(\d+(?:,\s?\d+)?\))?)$/', $meta_type ) ) { 295 return 'CHAR'; 296 } 297 298 if ( 'NUMERIC' === $meta_type ) { 299 $meta_type = 'SIGNED'; 300 } 301 302 return $meta_type; 303 } 304 305 /** 306 * Generates SQL clauses to be appended to a main query. 307 * 308 * @since 3.2.0 309 * 310 * @param string $type Type of meta, eg 'user', 'post'. 311 * @param string $primary_table Database table where the object being filtered is stored (eg wp_users). 312 * @param string $primary_id_column ID column for the filtered object in $primary_table. 313 * @param object $context Optional. The main query object. 314 * @return array|false { 315 * Array containing JOIN and WHERE SQL clauses to append to the main query. 316 * 317 * @type string $join SQL fragment to append to the main JOIN clause. 318 * @type string $where SQL fragment to append to the main WHERE clause. 319 * } 320 */ 321 public function get_sql( $type, $primary_table, $primary_id_column, $context = null ) { 322 $meta_table = _get_meta_table( $type ); 323 if ( ! $meta_table ) { 324 return false; 325 } 326 327 $this->table_aliases = array(); 328 329 $this->meta_table = $meta_table; 330 $this->meta_id_column = sanitize_key( $type . '_id' ); 331 332 $this->primary_table = $primary_table; 333 $this->primary_id_column = $primary_id_column; 334 335 $sql = $this->get_sql_clauses(); 336 337 /* 338 * If any JOINs are LEFT JOINs (as in the case of NOT EXISTS), then all JOINs should 339 * be LEFT. Otherwise posts with no metadata will be excluded from results. 340 */ 341 if ( false !== strpos( $sql['join'], 'LEFT JOIN' ) ) { 342 $sql['join'] = str_replace( 'INNER JOIN', 'LEFT JOIN', $sql['join'] ); 343 } 344 345 /** 346 * Filters the meta query's generated SQL. 347 * 348 * @since 3.1.0 349 * 350 * @param array $sql Array containing the query's JOIN and WHERE clauses. 351 * @param array $queries Array of meta queries. 352 * @param string $type Type of meta. 353 * @param string $primary_table Primary table. 354 * @param string $primary_id_column Primary column ID. 355 * @param object $context The main query object. 356 */ 357 return apply_filters_ref_array( 'get_meta_sql', array( $sql, $this->queries, $type, $primary_table, $primary_id_column, $context ) ); 358 } 359 360 /** 361 * Generate SQL clauses to be appended to a main query. 362 * 363 * Called by the public WP_Meta_Query::get_sql(), this method is abstracted 364 * out to maintain parity with the other Query classes. 365 * 366 * @since 4.1.0 367 * 368 * @return array { 369 * Array containing JOIN and WHERE SQL clauses to append to the main query. 370 * 371 * @type string $join SQL fragment to append to the main JOIN clause. 372 * @type string $where SQL fragment to append to the main WHERE clause. 373 * } 374 */ 375 protected function get_sql_clauses() { 376 /* 377 * $queries are passed by reference to get_sql_for_query() for recursion. 378 * To keep $this->queries unaltered, pass a copy. 379 */ 380 $queries = $this->queries; 381 $sql = $this->get_sql_for_query( $queries ); 382 383 if ( ! empty( $sql['where'] ) ) { 384 $sql['where'] = ' AND ' . $sql['where']; 385 } 386 387 return $sql; 388 } 389 390 /** 391 * Generate SQL clauses for a single query array. 392 * 393 * If nested subqueries are found, this method recurses the tree to 394 * produce the properly nested SQL. 395 * 396 * @since 4.1.0 397 * 398 * @param array $query Query to parse (passed by reference). 399 * @param int $depth Optional. Number of tree levels deep we currently are. 400 * Used to calculate indentation. Default 0. 401 * @return array { 402 * Array containing JOIN and WHERE SQL clauses to append to a single query array. 403 * 404 * @type string $join SQL fragment to append to the main JOIN clause. 405 * @type string $where SQL fragment to append to the main WHERE clause. 406 * } 407 */ 408 protected function get_sql_for_query( &$query, $depth = 0 ) { 409 $sql_chunks = array( 410 'join' => array(), 411 'where' => array(), 412 ); 413 414 $sql = array( 415 'join' => '', 416 'where' => '', 417 ); 418 419 $indent = ''; 420 for ( $i = 0; $i < $depth; $i++ ) { 421 $indent .= ' '; 422 } 423 424 foreach ( $query as $key => &$clause ) { 425 if ( 'relation' === $key ) { 426 $relation = $query['relation']; 427 } elseif ( is_array( $clause ) ) { 428 429 // This is a first-order clause. 430 if ( $this->is_first_order_clause( $clause ) ) { 431 $clause_sql = $this->get_sql_for_clause( $clause, $query, $key ); 432 433 $where_count = count( $clause_sql['where'] ); 434 if ( ! $where_count ) { 435 $sql_chunks['where'][] = ''; 436 } elseif ( 1 === $where_count ) { 437 $sql_chunks['where'][] = $clause_sql['where'][0]; 438 } else { 439 $sql_chunks['where'][] = '( ' . implode( ' AND ', $clause_sql['where'] ) . ' )'; 440 } 441 442 $sql_chunks['join'] = array_merge( $sql_chunks['join'], $clause_sql['join'] ); 443 // This is a subquery, so we recurse. 444 } else { 445 $clause_sql = $this->get_sql_for_query( $clause, $depth + 1 ); 446 447 $sql_chunks['where'][] = $clause_sql['where']; 448 $sql_chunks['join'][] = $clause_sql['join']; 449 } 450 } 451 } 452 453 // Filter to remove empties. 454 $sql_chunks['join'] = array_filter( $sql_chunks['join'] ); 455 $sql_chunks['where'] = array_filter( $sql_chunks['where'] ); 456 457 if ( empty( $relation ) ) { 458 $relation = 'AND'; 459 } 460 461 // Filter duplicate JOIN clauses and combine into a single string. 462 if ( ! empty( $sql_chunks['join'] ) ) { 463 $sql['join'] = implode( ' ', array_unique( $sql_chunks['join'] ) ); 464 } 465 466 // Generate a single WHERE clause with proper brackets and indentation. 467 if ( ! empty( $sql_chunks['where'] ) ) { 468 $sql['where'] = '( ' . "\n " . $indent . implode( ' ' . "\n " . $indent . $relation . ' ' . "\n " . $indent, $sql_chunks['where'] ) . "\n" . $indent . ')'; 469 } 470 471 return $sql; 472 } 473 474 /** 475 * Generate SQL JOIN and WHERE clauses for a first-order query clause. 476 * 477 * "First-order" means that it's an array with a 'key' or 'value'. 478 * 479 * @since 4.1.0 480 * 481 * @global wpdb $wpdb WordPress database abstraction object. 482 * 483 * @param array $clause Query clause (passed by reference). 484 * @param array $parent_query Parent query array. 485 * @param string $clause_key Optional. The array key used to name the clause in the original `$meta_query` 486 * parameters. If not provided, a key will be generated automatically. 487 * @return array { 488 * Array containing JOIN and WHERE SQL clauses to append to a first-order query. 489 * 490 * @type string $join SQL fragment to append to the main JOIN clause. 491 * @type string $where SQL fragment to append to the main WHERE clause. 492 * } 493 */ 494 public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) { 495 global $wpdb; 496 497 $sql_chunks = array( 498 'where' => array(), 499 'join' => array(), 500 ); 501 502 if ( isset( $clause['compare'] ) ) { 503 $clause['compare'] = strtoupper( $clause['compare'] ); 504 } else { 505 $clause['compare'] = isset( $clause['value'] ) && is_array( $clause['value'] ) ? 'IN' : '='; 506 } 507 508 $non_numeric_operators = array( 509 '=', 510 '!=', 511 'LIKE', 512 'NOT LIKE', 513 'IN', 514 'NOT IN', 515 'EXISTS', 516 'NOT EXISTS', 517 'RLIKE', 518 'REGEXP', 519 'NOT REGEXP', 520 ); 521 522 $numeric_operators = array( 523 '>', 524 '>=', 525 '<', 526 '<=', 527 'BETWEEN', 528 'NOT BETWEEN', 529 ); 530 531 if ( ! in_array( $clause['compare'], $non_numeric_operators, true ) && ! in_array( $clause['compare'], $numeric_operators, true ) ) { 532 $clause['compare'] = '='; 533 } 534 535 if ( isset( $clause['compare_key'] ) ) { 536 $clause['compare_key'] = strtoupper( $clause['compare_key'] ); 537 } else { 538 $clause['compare_key'] = isset( $clause['key'] ) && is_array( $clause['key'] ) ? 'IN' : '='; 539 } 540 541 if ( ! in_array( $clause['compare_key'], $non_numeric_operators, true ) ) { 542 $clause['compare_key'] = '='; 543 } 544 545 $meta_compare = $clause['compare']; 546 $meta_compare_key = $clause['compare_key']; 547 548 // First build the JOIN clause, if one is required. 549 $join = ''; 550 551 // We prefer to avoid joins if possible. Look for an existing join compatible with this clause. 552 $alias = $this->find_compatible_table_alias( $clause, $parent_query ); 553 if ( false === $alias ) { 554 $i = count( $this->table_aliases ); 555 $alias = $i ? 'mt' . $i : $this->meta_table; 556 557 // JOIN clauses for NOT EXISTS have their own syntax. 558 if ( 'NOT EXISTS' === $meta_compare ) { 559 $join .= " LEFT JOIN $this->meta_table"; 560 $join .= $i ? " AS $alias" : ''; 561 562 if ( 'LIKE' === $meta_compare_key ) { 563 $join .= $wpdb->prepare( " ON ($this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column AND $alias.meta_key LIKE %s )", '%' . $wpdb->esc_like( $clause['key'] ) . '%' ); 564 } else { 565 $join .= $wpdb->prepare( " ON ($this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column AND $alias.meta_key = %s )", $clause['key'] ); 566 } 567 568 // All other JOIN clauses. 569 } else { 570 $join .= " INNER JOIN $this->meta_table"; 571 $join .= $i ? " AS $alias" : ''; 572 $join .= " ON ( $this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column )"; 573 } 574 575 $this->table_aliases[] = $alias; 576 $sql_chunks['join'][] = $join; 577 } 578 579 // Save the alias to this clause, for future siblings to find. 580 $clause['alias'] = $alias; 581 582 // Determine the data type. 583 $_meta_type = isset( $clause['type'] ) ? $clause['type'] : ''; 584 $meta_type = $this->get_cast_for_type( $_meta_type ); 585 $clause['cast'] = $meta_type; 586 587 // Fallback for clause keys is the table alias. Key must be a string. 588 if ( is_int( $clause_key ) || ! $clause_key ) { 589 $clause_key = $clause['alias']; 590 } 591 592 // Ensure unique clause keys, so none are overwritten. 593 $iterator = 1; 594 $clause_key_base = $clause_key; 595 while ( isset( $this->clauses[ $clause_key ] ) ) { 596 $clause_key = $clause_key_base . '-' . $iterator; 597 $iterator++; 598 } 599 600 // Store the clause in our flat array. 601 $this->clauses[ $clause_key ] =& $clause; 602 603 // Next, build the WHERE clause. 604 605 // meta_key. 606 if ( array_key_exists( 'key', $clause ) ) { 607 if ( 'NOT EXISTS' === $meta_compare ) { 608 $sql_chunks['where'][] = $alias . '.' . $this->meta_id_column . ' IS NULL'; 609 } else { 610 /** 611 * In joined clauses negative operators have to be nested into a 612 * NOT EXISTS clause and flipped, to avoid returning records with 613 * matching post IDs but different meta keys. Here we prepare the 614 * nested clause. 615 */ 616 if ( in_array( $meta_compare_key, array( '!=', 'NOT IN', 'NOT LIKE', 'NOT EXISTS', 'NOT REGEXP' ), true ) ) { 617 // Negative clauses may be reused. 618 $i = count( $this->table_aliases ); 619 $subquery_alias = $i ? 'mt' . $i : $this->meta_table; 620 $this->table_aliases[] = $subquery_alias; 621 622 $meta_compare_string_start = 'NOT EXISTS ('; 623 $meta_compare_string_start .= "SELECT 1 FROM $wpdb->postmeta $subquery_alias "; 624 $meta_compare_string_start .= "WHERE $subquery_alias.post_ID = $alias.post_ID "; 625 $meta_compare_string_end = 'LIMIT 1'; 626 $meta_compare_string_end .= ')'; 627 } 628 629 switch ( $meta_compare_key ) { 630 case '=': 631 case 'EXISTS': 632 $where = $wpdb->prepare( "$alias.meta_key = %s", trim( $clause['key'] ) ); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared 633 break; 634 case 'LIKE': 635 $meta_compare_value = '%' . $wpdb->esc_like( trim( $clause['key'] ) ) . '%'; 636 $where = $wpdb->prepare( "$alias.meta_key LIKE %s", $meta_compare_value ); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared 637 break; 638 case 'IN': 639 $meta_compare_string = "$alias.meta_key IN (" . substr( str_repeat( ',%s', count( $clause['key'] ) ), 1 ) . ')'; 640 $where = $wpdb->prepare( $meta_compare_string, $clause['key'] ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared 641 break; 642 case 'RLIKE': 643 case 'REGEXP': 644 $operator = $meta_compare_key; 645 if ( isset( $clause['type_key'] ) && 'BINARY' === strtoupper( $clause['type_key'] ) ) { 646 $cast = 'BINARY'; 647 } else { 648 $cast = ''; 649 } 650 $where = $wpdb->prepare( "$alias.meta_key $operator $cast %s", trim( $clause['key'] ) ); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared 651 break; 652 653 case '!=': 654 case 'NOT EXISTS': 655 $meta_compare_string = $meta_compare_string_start . "AND $subquery_alias.meta_key = %s " . $meta_compare_string_end; 656 $where = $wpdb->prepare( $meta_compare_string, $clause['key'] ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared 657 break; 658 case 'NOT LIKE': 659 $meta_compare_string = $meta_compare_string_start . "AND $subquery_alias.meta_key LIKE %s " . $meta_compare_string_end; 660 661 $meta_compare_value = '%' . $wpdb->esc_like( trim( $clause['key'] ) ) . '%'; 662 $where = $wpdb->prepare( $meta_compare_string, $meta_compare_value ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared 663 break; 664 case 'NOT IN': 665 $array_subclause = '(' . substr( str_repeat( ',%s', count( $clause['key'] ) ), 1 ) . ') '; 666 $meta_compare_string = $meta_compare_string_start . "AND $subquery_alias.meta_key IN " . $array_subclause . $meta_compare_string_end; 667 $where = $wpdb->prepare( $meta_compare_string, $clause['key'] ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared 668 break; 669 case 'NOT REGEXP': 670 $operator = $meta_compare_key; 671 if ( isset( $clause['type_key'] ) && 'BINARY' === strtoupper( $clause['type_key'] ) ) { 672 $cast = 'BINARY'; 673 } else { 674 $cast = ''; 675 } 676 677 $meta_compare_string = $meta_compare_string_start . "AND $subquery_alias.meta_key REGEXP $cast %s " . $meta_compare_string_end; 678 $where = $wpdb->prepare( $meta_compare_string, $clause['key'] ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared 679 break; 680 } 681 682 $sql_chunks['where'][] = $where; 683 } 684 } 685 686 // meta_value. 687 if ( array_key_exists( 'value', $clause ) ) { 688 $meta_value = $clause['value']; 689 690 if ( in_array( $meta_compare, array( 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN' ), true ) ) { 691 if ( ! is_array( $meta_value ) ) { 692 $meta_value = preg_split( '/[,\s]+/', $meta_value ); 693 } 694 } else { 695 $meta_value = trim( $meta_value ); 696 } 697 698 switch ( $meta_compare ) { 699 case 'IN': 700 case 'NOT IN': 701 $meta_compare_string = '(' . substr( str_repeat( ',%s', count( $meta_value ) ), 1 ) . ')'; 702 $where = $wpdb->prepare( $meta_compare_string, $meta_value ); 703 break; 704 705 case 'BETWEEN': 706 case 'NOT BETWEEN': 707 $where = $wpdb->prepare( '%s AND %s', $meta_value[0], $meta_value[1] ); 708 break; 709 710 case 'LIKE': 711 case 'NOT LIKE': 712 $meta_value = '%' . $wpdb->esc_like( $meta_value ) . '%'; 713 $where = $wpdb->prepare( '%s', $meta_value ); 714 break; 715 716 // EXISTS with a value is interpreted as '='. 717 case 'EXISTS': 718 $meta_compare = '='; 719 $where = $wpdb->prepare( '%s', $meta_value ); 720 break; 721 722 // 'value' is ignored for NOT EXISTS. 723 case 'NOT EXISTS': 724 $where = ''; 725 break; 726 727 default: 728 $where = $wpdb->prepare( '%s', $meta_value ); 729 break; 730 731 } 732 733 if ( $where ) { 734 if ( 'CHAR' === $meta_type ) { 735 $sql_chunks['where'][] = "$alias.meta_value {$meta_compare} {$where}"; 736 } else { 737 $sql_chunks['where'][] = "CAST($alias.meta_value AS {$meta_type}) {$meta_compare} {$where}"; 738 } 739 } 740 } 741 742 /* 743 * Multiple WHERE clauses (for meta_key and meta_value) should 744 * be joined in parentheses. 745 */ 746 if ( 1 < count( $sql_chunks['where'] ) ) { 747 $sql_chunks['where'] = array( '( ' . implode( ' AND ', $sql_chunks['where'] ) . ' )' ); 748 } 749 750 return $sql_chunks; 751 } 752 753 /** 754 * Get a flattened list of sanitized meta clauses. 755 * 756 * This array should be used for clause lookup, as when the table alias and CAST type must be determined for 757 * a value of 'orderby' corresponding to a meta clause. 758 * 759 * @since 4.2.0 760 * 761 * @return array Meta clauses. 762 */ 763 public function get_clauses() { 764 return $this->clauses; 765 } 766 767 /** 768 * Identify an existing table alias that is compatible with the current 769 * query clause. 770 * 771 * We avoid unnecessary table joins by allowing each clause to look for 772 * an existing table alias that is compatible with the query that it 773 * needs to perform. 774 * 775 * An existing alias is compatible if (a) it is a sibling of `$clause` 776 * (ie, it's under the scope of the same relation), and (b) the combination 777 * of operator and relation between the clauses allows for a shared table join. 778 * In the case of WP_Meta_Query, this only applies to 'IN' clauses that are 779 * connected by the relation 'OR'. 780 * 781 * @since 4.1.0 782 * 783 * @param array $clause Query clause. 784 * @param array $parent_query Parent query of $clause. 785 * @return string|false Table alias if found, otherwise false. 786 */ 787 protected function find_compatible_table_alias( $clause, $parent_query ) { 788 $alias = false; 789 790 foreach ( $parent_query as $sibling ) { 791 // If the sibling has no alias yet, there's nothing to check. 792 if ( empty( $sibling['alias'] ) ) { 793 continue; 794 } 795 796 // We're only interested in siblings that are first-order clauses. 797 if ( ! is_array( $sibling ) || ! $this->is_first_order_clause( $sibling ) ) { 798 continue; 799 } 800 801 $compatible_compares = array(); 802 803 // Clauses connected by OR can share joins as long as they have "positive" operators. 804 if ( 'OR' === $parent_query['relation'] ) { 805 $compatible_compares = array( '=', 'IN', 'BETWEEN', 'LIKE', 'REGEXP', 'RLIKE', '>', '>=', '<', '<=' ); 806 807 // Clauses joined by AND with "negative" operators share a join only if they also share a key. 808 } elseif ( isset( $sibling['key'] ) && isset( $clause['key'] ) && $sibling['key'] === $clause['key'] ) { 809 $compatible_compares = array( '!=', 'NOT IN', 'NOT LIKE' ); 810 } 811 812 $clause_compare = strtoupper( $clause['compare'] ); 813 $sibling_compare = strtoupper( $sibling['compare'] ); 814 if ( in_array( $clause_compare, $compatible_compares, true ) && in_array( $sibling_compare, $compatible_compares, true ) ) { 815 $alias = $sibling['alias']; 816 break; 817 } 818 } 819 820 /** 821 * Filters the table alias identified as compatible with the current clause. 822 * 823 * @since 4.1.0 824 * 825 * @param string|false $alias Table alias, or false if none was found. 826 * @param array $clause First-order query clause. 827 * @param array $parent_query Parent of $clause. 828 * @param WP_Meta_Query $this WP_Meta_Query object. 829 */ 830 return apply_filters( 'meta_query_find_compatible_table_alias', $alias, $clause, $parent_query, $this ); 831 } 832 833 /** 834 * Checks whether the current query has any OR relations. 835 * 836 * In some cases, the presence of an OR relation somewhere in the query will require 837 * the use of a `DISTINCT` or `GROUP BY` keyword in the `SELECT` clause. The current 838 * method can be used in these cases to determine whether such a clause is necessary. 839 * 840 * @since 4.3.0 841 * 842 * @return bool True if the query contains any `OR` relations, otherwise false. 843 */ 844 public function has_or_relation() { 845 return $this->has_or_relation; 846 } 847 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Mon Jan 25 08:20:01 2021 | Cross-referenced by PHPXref |