| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Network API: WP_Network_Query class 4 * 5 * @package WordPress 6 * @subpackage Multisite 7 * @since 4.6.0 8 */ 9 10 /** 11 * Core class used for querying networks. 12 * 13 * @since 4.6.0 14 * 15 * @see WP_Network_Query::__construct() for accepted arguments. 16 */ 17 #[AllowDynamicProperties] 18 class WP_Network_Query { 19 20 /** 21 * SQL for database query. 22 * 23 * @since 4.6.0 24 * @var string 25 */ 26 public $request; 27 28 /** 29 * SQL query clauses. 30 * 31 * @since 4.6.0 32 * @var array{ 33 * select: string, 34 * from: string, 35 * where: array<string, string>, 36 * groupby: string, 37 * orderby: string, 38 * limits: string 39 * } 40 */ 41 protected $sql_clauses = array( 42 'select' => '', 43 'from' => '', 44 'where' => array(), 45 'groupby' => '', 46 'orderby' => '', 47 'limits' => '', 48 ); 49 50 /** 51 * Query vars set by the user. 52 * 53 * @since 4.6.0 54 * @var array<string, mixed> 55 */ 56 public $query_vars; 57 58 /** 59 * Default values for query vars. 60 * 61 * @since 4.6.0 62 * @var array<string, mixed> 63 */ 64 public $query_var_defaults; 65 66 /** 67 * List of networks located by the query. 68 * 69 * @since 4.6.0 70 * @var WP_Network[]|int[] 71 */ 72 public $networks; 73 74 /** 75 * The amount of found networks for the current query. 76 * 77 * @since 4.6.0 78 * @var int 79 * @phpstan-var non-negative-int 80 */ 81 public $found_networks = 0; 82 83 /** 84 * The number of pages. 85 * 86 * @since 4.6.0 87 * @var int 88 * @phpstan-var non-negative-int 89 */ 90 public $max_num_pages = 0; 91 92 /** 93 * Constructor. 94 * 95 * Sets up the network query, based on the query vars passed. 96 * 97 * @since 4.6.0 98 * 99 * @param string|array $query { 100 * Optional. Array or query string of network query parameters. Default empty. 101 * 102 * @type int[] $network__in Array of network IDs to include. Default empty. 103 * @type int[] $network__not_in Array of network IDs to exclude. Default empty. 104 * @type bool $count Whether to return a network count (true) or array of network objects. 105 * Default false. 106 * @type string $fields Network fields to return. Accepts 'ids' (returns an array of network IDs) 107 * or empty (returns an array of complete network objects). Default empty. 108 * @type int $number Maximum number of networks to retrieve. Default empty (no limit). 109 * @type int $offset Number of networks to offset the query. Used to build LIMIT clause. 110 * Default 0. 111 * @type bool $no_found_rows Whether to disable the `SQL_CALC_FOUND_ROWS` query. Default true. 112 * @type string|array $orderby Network status or array of statuses. Accepts 'id', 'domain', 'path', 113 * 'domain_length', 'path_length' and 'network__in'. Also accepts false, 114 * an empty array, or 'none' to disable `ORDER BY` clause. Default 'id'. 115 * @type string $order How to order retrieved networks. Accepts 'ASC', 'DESC'. Default 'ASC'. 116 * @type string $domain Limit results to those affiliated with a given domain. Default empty. 117 * @type string[] $domain__in Array of domains to include affiliated networks for. Default empty. 118 * @type string[] $domain__not_in Array of domains to exclude affiliated networks for. Default empty. 119 * @type string $path Limit results to those affiliated with a given path. Default empty. 120 * @type string[] $path__in Array of paths to include affiliated networks for. Default empty. 121 * @type string[] $path__not_in Array of paths to exclude affiliated networks for. Default empty. 122 * @type string $search Search term(s) to retrieve matching networks for. Default empty. 123 * @type bool $update_network_cache Whether to prime the cache for found networks. Default true. 124 * } 125 */ 126 public function __construct( $query = '' ) { 127 $this->query_var_defaults = array( 128 'network__in' => '', 129 'network__not_in' => '', 130 'count' => false, 131 'fields' => '', 132 'number' => '', 133 'offset' => '', 134 'no_found_rows' => true, 135 'orderby' => 'id', 136 'order' => 'ASC', 137 'domain' => '', 138 'domain__in' => '', 139 'domain__not_in' => '', 140 'path' => '', 141 'path__in' => '', 142 'path__not_in' => '', 143 'search' => '', 144 'update_network_cache' => true, 145 ); 146 147 if ( ! empty( $query ) ) { 148 $this->query( $query ); 149 } 150 } 151 152 /** 153 * Parses arguments passed to the network query with default query parameters. 154 * 155 * @since 4.6.0 156 * 157 * @param string|array $query WP_Network_Query arguments. See WP_Network_Query::__construct() for accepted arguments. 158 */ 159 public function parse_query( $query = '' ) { 160 if ( empty( $query ) ) { 161 $query = $this->query_vars; 162 } 163 164 $this->query_vars = wp_parse_args( $query, $this->query_var_defaults ); 165 166 /** 167 * Fires after the network query vars have been parsed. 168 * 169 * @since 4.6.0 170 * 171 * @param WP_Network_Query $query The WP_Network_Query instance (passed by reference). 172 */ 173 do_action_ref_array( 'parse_network_query', array( &$this ) ); 174 } 175 176 /** 177 * Sets up the WordPress query for retrieving networks. 178 * 179 * @since 4.6.0 180 * 181 * @param string|array $query Array or URL query string of parameters. 182 * @return WP_Network[]|int[]|int List of WP_Network objects, a list of network IDs when 'fields' is set 183 * to 'ids', or the number of networks when 'count' is passed as a query var. 184 * 185 * @phpstan-return ( 186 * $query is array{ count: true, ... } ? int : ( 187 * $query is array{ fields: 'ids', ... } ? int[] : array<int, WP_Network> 188 * ) 189 * ) 190 */ 191 public function query( $query ) { 192 $this->query_vars = wp_parse_args( $query ); 193 return $this->get_networks(); 194 } 195 196 /** 197 * Gets a list of networks matching the query vars. 198 * 199 * @since 4.6.0 200 * 201 * @return WP_Network[]|int[]|int List of WP_Network objects, a list of network IDs when 'fields' is set 202 * to 'ids', or the number of networks when 'count' is passed as a query var. 203 */ 204 public function get_networks() { 205 $this->parse_query(); 206 207 /** 208 * Fires before networks are retrieved. 209 * 210 * @since 4.6.0 211 * 212 * @param WP_Network_Query $query Current instance of WP_Network_Query (passed by reference). 213 */ 214 do_action_ref_array( 'pre_get_networks', array( &$this ) ); 215 216 $network_data = null; 217 218 /** 219 * Filters the network data before the query takes place. 220 * 221 * Return a non-null value to bypass WordPress' default network queries. 222 * 223 * The expected return type from this filter depends on the value passed 224 * in the request query vars: 225 * - When `$this->query_vars['count']` is set, the filter should return 226 * the network count as an integer. 227 * - When `'ids' === $this->query_vars['fields']`, the filter should return 228 * an array of network IDs. 229 * - Otherwise the filter should return an array of WP_Network objects. 230 * 231 * Note that if the filter returns an array of network data, it will be assigned 232 * to the `networks` property of the current WP_Network_Query instance. 233 * 234 * Filtering functions that require pagination information are encouraged to set 235 * the `found_networks` and `max_num_pages` properties of the WP_Network_Query object, 236 * passed to the filter by reference. If WP_Network_Query does not perform a database 237 * query, it will not have enough information to generate these values itself. 238 * 239 * @since 5.2.0 240 * @since 5.6.0 The returned array of network data is assigned to the `networks` property 241 * of the current WP_Network_Query instance. 242 * 243 * @param WP_Network[]|int[]|int|null $network_data Return an array of network data to short-circuit WP's 244 * network query, the network count as an integer if 245 * `$this->query_vars['count']` is set, or null to allow WP 246 * to run its normal queries. 247 * @param WP_Network_Query $query The WP_Network_Query instance, passed by reference. 248 */ 249 $network_data = apply_filters_ref_array( 'networks_pre_query', array( $network_data, &$this ) ); 250 251 if ( null !== $network_data ) { 252 if ( is_array( $network_data ) && ! $this->query_vars['count'] ) { 253 $this->networks = $network_data; 254 } 255 256 return $network_data; 257 } 258 259 // $args can include anything. Only use the args defined in the query_var_defaults to compute the key. 260 $_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) ); 261 262 // Ignore the $fields, $update_network_cache arguments as the queried result will be the same regardless. 263 unset( $_args['fields'], $_args['update_network_cache'] ); 264 265 $key = md5( serialize( $_args ) ); 266 $last_changed = wp_cache_get_last_changed( 'networks' ); 267 268 $cache_key = "get_network_ids:$key"; 269 $cache_value = wp_cache_get_salted( $cache_key, 'network-queries', $last_changed ); 270 271 if ( false === $cache_value ) { 272 $network_ids = $this->get_network_ids(); 273 if ( $network_ids ) { 274 $this->set_found_networks(); 275 } 276 277 $cache_value = array( 278 'network_ids' => $network_ids, 279 'found_networks' => $this->found_networks, 280 ); 281 wp_cache_set_salted( $cache_key, $cache_value, 'network-queries', $last_changed ); 282 } else { 283 $network_ids = $cache_value['network_ids']; 284 $this->found_networks = $cache_value['found_networks']; 285 } 286 287 if ( $this->found_networks && $this->query_vars['number'] ) { 288 $this->max_num_pages = (int) ceil( $this->found_networks / $this->query_vars['number'] ); 289 } 290 291 // If querying for a count only, there's nothing more to do. 292 if ( $this->query_vars['count'] ) { 293 // $network_ids is actually a count in this case. 294 return (int) $network_ids; 295 } 296 297 $network_ids = array_map( 'intval', $network_ids ); 298 299 if ( 'ids' === $this->query_vars['fields'] ) { 300 $this->networks = $network_ids; 301 return $this->networks; 302 } 303 304 if ( $this->query_vars['update_network_cache'] ) { 305 _prime_network_caches( $network_ids ); 306 } 307 308 // Fetch full network objects from the primed cache. 309 $_networks = array(); 310 foreach ( $network_ids as $network_id ) { 311 $_network = get_network( $network_id ); 312 if ( $_network ) { 313 $_networks[] = $_network; 314 } 315 } 316 317 /** 318 * Filters the network query results. 319 * 320 * @since 4.6.0 321 * 322 * @param WP_Network[] $_networks An array of WP_Network objects. 323 * @param WP_Network_Query $query Current instance of WP_Network_Query (passed by reference). 324 */ 325 $_networks = apply_filters_ref_array( 'the_networks', array( $_networks, &$this ) ); 326 327 // Convert to WP_Network instances. 328 $this->networks = array_map( 'get_network', $_networks ); 329 330 return $this->networks; 331 } 332 333 /** 334 * Used internally to get a list of network IDs matching the query vars. 335 * 336 * @since 4.6.0 337 * 338 * @global wpdb $wpdb WordPress database abstraction object. 339 * 340 * @return int|array A single count of network IDs if a count query. An array of network IDs if a full query. 341 */ 342 protected function get_network_ids() { 343 global $wpdb; 344 345 $order = $this->parse_order( $this->query_vars['order'] ); 346 347 // Disable ORDER BY with 'none', an empty array, or boolean false. 348 if ( in_array( $this->query_vars['orderby'], array( 'none', array(), false ), true ) ) { 349 $orderby = ''; 350 } elseif ( ! empty( $this->query_vars['orderby'] ) ) { 351 $ordersby = is_array( $this->query_vars['orderby'] ) ? 352 $this->query_vars['orderby'] : 353 preg_split( '/[,\s]/', $this->query_vars['orderby'] ); 354 355 $orderby_array = array(); 356 foreach ( $ordersby as $_key => $_value ) { 357 if ( ! $_value ) { 358 continue; 359 } 360 361 if ( is_int( $_key ) ) { 362 $_orderby = $_value; 363 $_order = $order; 364 } else { 365 $_orderby = $_key; 366 $_order = $_value; 367 } 368 369 $parsed = $this->parse_orderby( $_orderby ); 370 371 if ( ! $parsed ) { 372 continue; 373 } 374 375 if ( 'network__in' === $_orderby ) { 376 $orderby_array[] = $parsed; 377 continue; 378 } 379 380 $orderby_array[] = $parsed . ' ' . $this->parse_order( $_order ); 381 } 382 383 $orderby = implode( ', ', $orderby_array ); 384 } else { 385 $orderby = "$wpdb->site.id $order"; 386 } 387 388 $number = absint( $this->query_vars['number'] ); 389 $offset = absint( $this->query_vars['offset'] ); 390 $limits = ''; 391 392 if ( ! empty( $number ) ) { 393 if ( $offset ) { 394 $limits = 'LIMIT ' . $offset . ',' . $number; 395 } else { 396 $limits = 'LIMIT ' . $number; 397 } 398 } 399 400 if ( $this->query_vars['count'] ) { 401 $fields = 'COUNT(*)'; 402 } else { 403 $fields = "$wpdb->site.id"; 404 } 405 406 // Parse network IDs for an IN clause. 407 if ( ! empty( $this->query_vars['network__in'] ) ) { 408 $this->sql_clauses['where']['network__in'] = "$wpdb->site.id IN ( " . implode( ',', wp_parse_id_list( $this->query_vars['network__in'] ) ) . ' )'; 409 } 410 411 // Parse network IDs for a NOT IN clause. 412 if ( ! empty( $this->query_vars['network__not_in'] ) ) { 413 $this->sql_clauses['where']['network__not_in'] = "$wpdb->site.id NOT IN ( " . implode( ',', wp_parse_id_list( $this->query_vars['network__not_in'] ) ) . ' )'; 414 } 415 416 if ( ! empty( $this->query_vars['domain'] ) ) { 417 $this->sql_clauses['where']['domain'] = $wpdb->prepare( "$wpdb->site.domain = %s", $this->query_vars['domain'] ); 418 } 419 420 // Parse network domain for an IN clause. 421 if ( is_array( $this->query_vars['domain__in'] ) ) { 422 $this->sql_clauses['where']['domain__in'] = "$wpdb->site.domain IN ( '" . implode( "', '", $wpdb->_escape( $this->query_vars['domain__in'] ) ) . "' )"; 423 } 424 425 // Parse network domain for a NOT IN clause. 426 if ( is_array( $this->query_vars['domain__not_in'] ) ) { 427 $this->sql_clauses['where']['domain__not_in'] = "$wpdb->site.domain NOT IN ( '" . implode( "', '", $wpdb->_escape( $this->query_vars['domain__not_in'] ) ) . "' )"; 428 } 429 430 if ( ! empty( $this->query_vars['path'] ) ) { 431 $this->sql_clauses['where']['path'] = $wpdb->prepare( "$wpdb->site.path = %s", $this->query_vars['path'] ); 432 } 433 434 // Parse network path for an IN clause. 435 if ( is_array( $this->query_vars['path__in'] ) ) { 436 $this->sql_clauses['where']['path__in'] = "$wpdb->site.path IN ( '" . implode( "', '", $wpdb->_escape( $this->query_vars['path__in'] ) ) . "' )"; 437 } 438 439 // Parse network path for a NOT IN clause. 440 if ( is_array( $this->query_vars['path__not_in'] ) ) { 441 $this->sql_clauses['where']['path__not_in'] = "$wpdb->site.path NOT IN ( '" . implode( "', '", $wpdb->_escape( $this->query_vars['path__not_in'] ) ) . "' )"; 442 } 443 444 // Falsey search strings are ignored. 445 if ( strlen( $this->query_vars['search'] ) ) { 446 $this->sql_clauses['where']['search'] = $this->get_search_sql( 447 $this->query_vars['search'], 448 array( "$wpdb->site.domain", "$wpdb->site.path" ) 449 ); 450 } 451 452 $join = ''; 453 454 $where = implode( ' AND ', $this->sql_clauses['where'] ); 455 456 $groupby = ''; 457 458 $pieces = array( 'fields', 'join', 'where', 'orderby', 'limits', 'groupby' ); 459 460 /** 461 * Filters the network query clauses. 462 * 463 * @since 4.6.0 464 * 465 * @param string[] $clauses { 466 * Associative array of the clauses for the query. 467 * 468 * @type string $fields The SELECT clause of the query. 469 * @type string $join The JOIN clause of the query. 470 * @type string $where The WHERE clause of the query. 471 * @type string $orderby The ORDER BY clause of the query. 472 * @type string $limits The LIMIT clause of the query. 473 * @type string $groupby The GROUP BY clause of the query. 474 * } 475 * @param WP_Network_Query $query Current instance of WP_Network_Query (passed by reference). 476 */ 477 $clauses = apply_filters_ref_array( 'networks_clauses', array( compact( $pieces ), &$this ) ); 478 479 $fields = $clauses['fields'] ?? ''; 480 $join = $clauses['join'] ?? ''; 481 $where = $clauses['where'] ?? ''; 482 $orderby = $clauses['orderby'] ?? ''; 483 $limits = $clauses['limits'] ?? ''; 484 $groupby = $clauses['groupby'] ?? ''; 485 486 if ( $where ) { 487 $where = 'WHERE ' . $where; 488 } 489 490 if ( $groupby ) { 491 $groupby = 'GROUP BY ' . $groupby; 492 } 493 494 if ( $orderby ) { 495 $orderby = "ORDER BY $orderby"; 496 } 497 498 $found_rows = ''; 499 if ( ! $this->query_vars['no_found_rows'] ) { 500 $found_rows = 'SQL_CALC_FOUND_ROWS'; 501 } 502 503 $this->sql_clauses['select'] = "SELECT $found_rows $fields"; 504 $this->sql_clauses['from'] = "FROM $wpdb->site $join"; 505 $this->sql_clauses['groupby'] = $groupby; 506 $this->sql_clauses['orderby'] = $orderby; 507 $this->sql_clauses['limits'] = $limits; 508 509 // Beginning of the string is on a new line to prevent leading whitespace. See https://core.trac.wordpress.org/ticket/56841. 510 $this->request = 511 "{$this->sql_clauses['select']} 512 {$this->sql_clauses['from']} 513 {$where} 514 {$this->sql_clauses['groupby']} 515 {$this->sql_clauses['orderby']} 516 {$this->sql_clauses['limits']}"; 517 518 if ( $this->query_vars['count'] ) { 519 return (int) $wpdb->get_var( $this->request ); 520 } 521 522 $network_ids = $wpdb->get_col( $this->request ); 523 524 return array_map( 'intval', $network_ids ); 525 } 526 527 /** 528 * Populates found_networks and max_num_pages properties for the current query 529 * if the limit clause was used. 530 * 531 * @since 4.6.0 532 * 533 * @global wpdb $wpdb WordPress database abstraction object. 534 */ 535 private function set_found_networks() { 536 global $wpdb; 537 538 if ( $this->query_vars['number'] && ! $this->query_vars['no_found_rows'] ) { 539 /** 540 * Filters the query used to retrieve found network count. 541 * 542 * @since 4.6.0 543 * 544 * @param string $found_networks_query SQL query. Default 'SELECT FOUND_ROWS()'. 545 * @param WP_Network_Query $network_query The `WP_Network_Query` instance. 546 */ 547 $found_networks_query = apply_filters( 'found_networks_query', 'SELECT FOUND_ROWS()', $this ); 548 549 $this->found_networks = (int) $wpdb->get_var( $found_networks_query ); 550 } 551 } 552 553 /** 554 * Used internally to generate an SQL string for searching across multiple columns. 555 * 556 * @since 4.6.0 557 * 558 * @global wpdb $wpdb WordPress database abstraction object. 559 * 560 * @param string $search Search string. 561 * @param string[] $columns Array of columns to search. 562 * @return string Search SQL. 563 */ 564 protected function get_search_sql( $search, $columns ) { 565 global $wpdb; 566 567 $like = '%' . $wpdb->esc_like( $search ) . '%'; 568 569 $searches = array(); 570 foreach ( $columns as $column ) { 571 $searches[] = $wpdb->prepare( "$column LIKE %s", $like ); 572 } 573 574 return '(' . implode( ' OR ', $searches ) . ')'; 575 } 576 577 /** 578 * Parses and sanitizes 'orderby' keys passed to the network query. 579 * 580 * @since 4.6.0 581 * 582 * @global wpdb $wpdb WordPress database abstraction object. 583 * 584 * @param string $orderby Alias for the field to order by. 585 * @return string|false Value to used in the ORDER clause. False otherwise. 586 */ 587 protected function parse_orderby( $orderby ) { 588 global $wpdb; 589 590 $allowed_keys = array( 591 'id', 592 'domain', 593 'path', 594 ); 595 596 $parsed = false; 597 if ( 'network__in' === $orderby ) { 598 $network__in = implode( ',', array_map( 'absint', $this->query_vars['network__in'] ) ); 599 $parsed = "FIELD( {$wpdb->site}.id, $network__in )"; 600 } elseif ( 'domain_length' === $orderby || 'path_length' === $orderby ) { 601 $field = substr( $orderby, 0, -7 ); 602 $parsed = "CHAR_LENGTH($wpdb->site.$field)"; 603 } elseif ( in_array( $orderby, $allowed_keys, true ) ) { 604 $parsed = "$wpdb->site.$orderby"; 605 } 606 607 return $parsed; 608 } 609 610 /** 611 * Parses an 'order' query variable and cast it to 'ASC' or 'DESC' as necessary. 612 * 613 * @since 4.6.0 614 * 615 * @param string $order The 'order' query variable. 616 * @return string The sanitized 'order' query variable. 617 */ 618 protected function parse_order( $order ) { 619 if ( ! is_string( $order ) || empty( $order ) ) { 620 return 'ASC'; 621 } 622 623 if ( 'ASC' === strtoupper( $order ) ) { 624 return 'ASC'; 625 } else { 626 return 'DESC'; 627 } 628 } 629 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sun Oct 11 08:20:32 2026 | Cross-referenced by PHPXref |