enmi-conf.org: comparison wp/wp-includes/class-wp-network-query.php

equal deleted inserted replaced

-:34716fd837a4
+:be944660c56a
 	 * @since 4.6.0
 	 *
 	 * @param string|array $query {
 	 *     Optional. Array or query string of network query parameters. Default empty.
 	 *
-	 *     @type array        $network__in          Array of network IDs to include. Default empty.
+	 *     @type int[]        $network__in          Array of network IDs to include. Default empty.
-	 *     @type array        $network__not_in      Array of network IDs to exclude. Default empty.
+	 *     @type int[]        $network__not_in      Array of network IDs to exclude. Default empty.
 	 *     @type bool         $count                Whether to return a network count (true) or array of network objects.
 	 *                                              Default false.
 	 *     @type string       $fields               Network fields to return. Accepts 'ids' (returns an array of network IDs)
 	 *                                              or empty (returns an array of complete network objects). Default empty.
 	 *     @type int          $number               Maximum number of networks to retrieve. Default empty (no limit).
 	 *     @type string|array $orderby              Network status or array of statuses. Accepts 'id', 'domain', 'path',
 	 *                                              'domain_length', 'path_length' and 'network__in'. Also accepts false,
 	 *                                              an empty array, or 'none' to disable `ORDER BY` clause. Default 'id'.
 	 *     @type string       $order                How to order retrieved networks. Accepts 'ASC', 'DESC'. Default 'ASC'.
 	 *     @type string       $domain               Limit results to those affiliated with a given domain. Default empty.
-	 *     @type array        $domain__in           Array of domains to include affiliated networks for. Default empty.
+	 *     @type string[]     $domain__in           Array of domains to include affiliated networks for. Default empty.
-	 *     @type array        $domain__not_in       Array of domains to exclude affiliated networks for. Default empty.
+	 *     @type string[]     $domain__not_in       Array of domains to exclude affiliated networks for. Default empty.
 	 *     @type string       $path                 Limit results to those affiliated with a given path. Default empty.
-	 *     @type array        $path__in             Array of paths to include affiliated networks for. Default empty.
+	 *     @type string[]     $path__in             Array of paths to include affiliated networks for. Default empty.
-	 *     @type array        $path__not_in         Array of paths to exclude affiliated networks for. Default empty.
+	 *     @type string[]     $path__not_in         Array of paths to exclude affiliated networks for. Default empty.
 	 *     @type string       $search               Search term(s) to retrieve matching networks for. Default empty.
 	 *     @type bool         $update_network_cache Whether to prime the cache for found networks. Default true.
 	 * }
 	 */
 	public function __construct( $query = '' ) {
 		do_action_ref_array( 'pre_get_networks', array( &$this ) );
 		$network_data = null;
 		/**
-		 * Filter the network data before the query takes place.
+		 * Filters the network data before the query takes place.
 		 *
-		 * Return a non-null value to bypass WordPress's default network queries.
+		 * Return a non-null value to bypass WordPress' default network queries.
 		 *
-		 * The expected return type from this filter depends on the value passed in the request query_vars.
+		 * The expected return type from this filter depends on the value passed
-		 * When `$this->query_vars['count']` is set, the filter should return the network count as an int.
+		 * in the request query vars:
-		 * When `'ids' === $this->query_vars['fields']`, the filter should return an array of network IDs.
+		 * - When `$this->query_vars['count']` is set, the filter should return
-		 * Otherwise the filter should return an array of WP_Network objects.
+		 *   the network count as an integer.
+		 * - When `'ids' === $this->query_vars['fields']`, the filter should return
+		 *   an array of network IDs.
+		 * - Otherwise the filter should return an array of WP_Network objects.
+		 *
+		 * Note that if the filter returns an array of network data, it will be assigned
+		 * to the `networks` property of the current WP_Network_Query instance.
+		 *
+		 * Filtering functions that require pagination information are encouraged to set
+		 * the `found_networks` and `max_num_pages` properties of the WP_Network_Query object,
+		 * passed to the filter by reference. If WP_Network_Query does not perform a database
+		 * query, it will not have enough information to generate these values itself.
 		 *
 		 * @since 5.2.0
-		 *
+		 * @since 5.6.0 The returned array of network data is assigned to the `networks` property
-		 * @param array|null       $network_data Return an array of network data to short-circuit WP's network query,
+		 *              of the current WP_Network_Query instance.
+		 *
+		 * @param array|int|null   $network_data Return an array of network data to short-circuit WP's network query,
 		 *                                       the network count as an integer if `$this->query_vars['count']` is set,
 		 *                                       or null to allow WP to run its normal queries.
-		 * @param WP_Network_Query $this         The WP_Network_Query instance, passed by reference.
+		 * @param WP_Network_Query $query        The WP_Network_Query instance, passed by reference.
 		 */
 		$network_data = apply_filters_ref_array( 'networks_pre_query', array( $network_data, &$this ) );
 		if ( null !== $network_data ) {
+			if ( is_array( $network_data ) && ! $this->query_vars['count'] ) {
+				$this->networks = $network_data;
+			}
 			return $network_data;
 		}
 		// $args can include anything. Only use the args defined in the query_var_defaults to compute the key.
 		$_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) );
 		}
 		// If querying for a count only, there's nothing more to do.
 		if ( $this->query_vars['count'] ) {
 			// $network_ids is actually a count in this case.
-			return intval( $network_ids );
+			return (int) $network_ids;
 		}
 		$network_ids = array_map( 'intval', $network_ids );
 		if ( 'ids' === $this->query_vars['fields'] ) {
 		 * Filters the network query results.
 		 *
 		 * @since 4.6.0
 		 *
 		 * @param WP_Network[]     $_networks An array of WP_Network objects.
-		 * @param WP_Network_Query $this      Current instance of WP_Network_Query (passed by reference).
+		 * @param WP_Network_Query $query     Current instance of WP_Network_Query (passed by reference).
 		 */
 		$_networks = apply_filters_ref_array( 'the_networks', array( $_networks, &$this ) );
 		// Convert to WP_Network instances.
 		$this->networks = array_map( 'get_network', $_networks );
 		 * Filters the network query clauses.
 		 *
 		 * @since 4.6.0
 		 *
 		 * @param string[]         $pieces An associative array of network query clauses.
-		 * @param WP_Network_Query $this   Current instance of WP_Network_Query (passed by reference).
+		 * @param WP_Network_Query $query  Current instance of WP_Network_Query (passed by reference).
 		 */
 		$clauses = apply_filters_ref_array( 'networks_clauses', array( compact( $pieces ), &$this ) );
 		$fields  = isset( $clauses['fields'] ) ? $clauses['fields'] : '';
 		$join    = isset( $clauses['join'] ) ? $clauses['join'] : '';
 		$this->sql_clauses['limits']  = $limits;
 		$this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['groupby']} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}";
 		if ( $this->query_vars['count'] ) {
-			return intval( $wpdb->get_var( $this->request ) );
+			return (int) $wpdb->get_var( $this->request );
 		}
 		$network_ids = $wpdb->get_col( $this->request );
 		return array_map( 'intval', $network_ids );

changeset 18	be944660c56a
parent 16	a86126ab1dd4
child 19	3d72ae0968f4