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