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

equal deleted inserted replaced

-:34716fd837a4
+:be944660c56a
 	 * @param string|array $query {
 	 *     Optional. Array or query string of term query parameters. Default empty.
 	 *
 	 *     @type string|array $taxonomy               Taxonomy name, or array of taxonomies, to which results should
 	 *                                                be limited.
-	 *     @type int|array    $object_ids             Optional. Object ID, or array of object IDs. Results will be
+	 *     @type int|int[]    $object_ids             Optional. Object ID, or array of object IDs. Results will be
 	 *                                                limited to terms associated with these objects.
 	 *     @type string       $orderby                Field(s) to order terms by. Accepts:
-	 *                                                - term fields ('name', 'slug', 'term_group', 'term_id', 'id',
+	 *                                                * term fields ('name', 'slug', 'term_group', 'term_id', 'id',
 	 *                                                  'description', 'parent', 'term_order'). Unless `$object_ids`
 	 *                                                  is not empty, 'term_order' is treated the same as 'term_id'.
-	 *                                                - 'count' for term taxonomy count.
+	 *                                                * 'count' to use the number of objects associated with the term.
-	 *                                                - 'include' to match the 'order' of the $include param.
+	 *                                                * 'include' to match the 'order' of the $include param.
-	 *                                                - 'slug__in' to match the 'order' of the $slug param.
+	 *                                                * 'slug__in' to match the 'order' of the $slug param.
-	 *                                                - 'meta_value', 'meta_value_num'.
+	 *                                                * 'meta_value', 'meta_value_num'.
-	 *                                                - the value of `$meta_key`.
+	 *                                                  the value of `$meta_key`.
-	 *                                                - the array keys of `$meta_query`.
+	 *                                                  the array keys of `$meta_query`.
-	 *                                                - 'none' to omit the ORDER BY clause.
+	 *                                                * 'none' to omit the ORDER BY clause.
 	 *                                                Defaults to 'name'.
 	 *     @type string       $order                  Whether to order terms in ascending or descending order.
 	 *                                                Accepts 'ASC' (ascending) or 'DESC' (descending).
 	 *                                                Default 'ASC'.
 	 *     @type bool|int     $hide_empty             Whether to hide terms not assigned to any posts. Accepts
 	 *                                                1|true or 0|false. Default 1|true.
-	 *     @type array|string $include                Array or comma/space-separated string of term IDs to include.
+	 *     @type int[]|string $include                Array or comma/space-separated string of term IDs to include.
 	 *                                                Default empty array.
-	 *     @type array|string $exclude                Array or comma/space-separated string of term IDs to exclude.
+	 *     @type int[]|string $exclude                Array or comma/space-separated string of term IDs to exclude.
 	 *                                                If $include is non-empty, $exclude is ignored.
 	 *                                                Default empty array.
-	 *     @type array|string $exclude_tree           Array or comma/space-separated string of term IDs to exclude
+	 *     @type int[]|string $exclude_tree           Array or comma/space-separated string of term IDs to exclude
 	 *                                                along with all of their descendant terms. If $include is
 	 *                                                non-empty, $exclude_tree is ignored. Default empty array.
 	 *     @type int|string   $number                 Maximum number of terms to return. Accepts ''|0 (all) or any
 	 *                                                positive number. Default ''|0 (all). Note that $number may
 	 *                                                not return accurate results when coupled with $object_ids.
 	 *                                                See #41796 for details.
 	 *     @type int          $offset                 The number by which to offset the terms query. Default empty.
 	 *     @type string       $fields                 Term fields to query for. Accepts:
-	 *                                                - 'all' Returns an array of complete term objects (`WP_Term[]`).
+	 *                                                * 'all' Returns an array of complete term objects (`WP_Term[]`).
-	 *                                                - 'all_with_object_id' Returns an array of term objects
+	 *                                                * 'all_with_object_id' Returns an array of term objects
 	 *                                                  with the 'object_id' param (`WP_Term[]`). Works only
 	 *                                                  when the `$object_ids` parameter is populated.
-	 *                                                - 'ids' Returns an array of term IDs (`int[]`).
+	 *                                                * 'ids' Returns an array of term IDs (`int[]`).
-	 *                                                - 'tt_ids' Returns an array of term taxonomy IDs (`int[]`).
+	 *                                                * 'tt_ids' Returns an array of term taxonomy IDs (`int[]`).
-	 *                                                - 'names' Returns an array of term names (`string[]`).
+	 *                                                * 'names' Returns an array of term names (`string[]`).
-	 *                                                - 'slugs' Returns an array of term slugs (`string[]`).
+	 *                                                * 'slugs' Returns an array of term slugs (`string[]`).
-	 *                                                - 'count' Returns the number of matching terms (`int`).
+	 *                                                * 'count' Returns the number of matching terms (`int`).
-	 *                                                - 'id=>parent' Returns an associative array of parent term IDs,
+	 *                                                * 'id=>parent' Returns an associative array of parent term IDs,
 	 *                                                   keyed by term ID (`int[]`).
-	 *                                                - 'id=>name' Returns an associative array of term names,
+	 *                                                * 'id=>name' Returns an associative array of term names,
 	 *                                                   keyed by term ID (`string[]`).
-	 *                                                - 'id=>slug' Returns an associative array of term slugs,
+	 *                                                * 'id=>slug' Returns an associative array of term slugs,
 	 *                                                   keyed by term ID (`string[]`).
 	 *                                                Default 'all'.
 	 *     @type bool         $count                  Whether to return a term count. If true, will take precedence
 	 *                                                over `$fields`. Default false.
 	 *     @type string|array $name                   Optional. Name or array of names to return term(s) for.
 	 *                                                Default empty.
 	 *     @type string|array $slug                   Optional. Slug or array of slugs to return term(s) for.
 	 *                                                Default empty.
-	 *     @type int|array    $term_taxonomy_id       Optional. Term taxonomy ID, or array of term taxonomy IDs,
+	 *     @type int|int[]    $term_taxonomy_id       Optional. Term taxonomy ID, or array of term taxonomy IDs,
 	 *                                                to match when querying terms.
 	 *     @type bool         $hierarchical           Whether to include terms that have non-empty descendants
 	 *                                                (even if $hide_empty is set to true). Default true.
 	 *     @type string       $search                 Search criteria to match terms. Will be SQL-formatted with
 	 *                                                wildcards before and after. Default empty.
 		$query['number'] = absint( $query['number'] );
 		$query['offset'] = absint( $query['offset'] );
 		// 'parent' overrides 'child_of'.
-		if ( 0 < intval( $query['parent'] ) ) {
+		if ( 0 < (int) $query['parent'] ) {
 			$query['child_of'] = false;
 		}
 		if ( 'all' === $query['get'] ) {
 			$query['childless']    = false;
 		 */
 		do_action( 'parse_term_query', $this );
 	}
 	/**
-	 * Sets up the query for retrieving terms.
+	 * Sets up the query and retrieves the results.
+	 *
+	 * The return type varies depending on the value passed to `$args['fields']`. See
+	 * WP_Term_Query::get_terms() for details.
 	 *
 	 * @since 4.6.0
 	 *
 	 * @param string|array $query Array or URL query string of parameters.
-	 * @return array|int List of terms, or number of terms when 'count' is passed as a query var.
+	 * @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string
+	 *                                         when 'count' is passed as a query var.
 	 */
 	public function query( $query ) {
 		$this->query_vars = wp_parse_args( $query );
 		return $this->get_terms();
 	}
 	/**
-	 * Get terms, based on query_vars.
+	 * Retrieves the query results.
+	 *
+	 * The return type varies depending on the value passed to `$args['fields']`.
+	 *
+	 * The following will result in an array of `WP_Term` objects being returned:
+	 *
+	 *   - 'all'
+	 *   - 'all_with_object_id'
+	 *
+	 * The following will result in a numeric string being returned:
+	 *
+	 *   - 'count'
+	 *
+	 * The following will result in an array of text strings being returned:
+	 *
+	 *   - 'id=>name'
+	 *   - 'id=>slug'
+	 *   - 'names'
+	 *   - 'slugs'
+	 *
+	 * The following will result in an array of numeric strings being returned:
+	 *
+	 *   - 'id=>parent'
+	 *
+	 * The following will result in an array of integers being returned:
+	 *
+	 *   - 'ids'
+	 *   - 'tt_ids'
 	 *
 	 * @since 4.6.0
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @return array List of terms.
+	 * @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string
+	 *                                         when 'count' is passed as a query var.
 	 */
 	public function get_terms() {
 		global $wpdb;
 		$this->parse_query( $this->query_vars );
 		/**
 		 * Fires before terms are retrieved.
 		 *
 		 * @since 4.6.0
 		 *
-		 * @param WP_Term_Query $this Current instance of WP_Term_Query.
+		 * @param WP_Term_Query $this Current instance of WP_Term_Query (passed by reference).
 		 */
-		do_action( 'pre_get_terms', $this );
+		do_action_ref_array( 'pre_get_terms', array( &$this ) );
 		$taxonomies = (array) $args['taxonomy'];
 		// Save queries by not crawling the tree in the case of multiple taxes or a flat tax.
 		$has_hierarchical_tax = false;
 			$args['hierarchical'] = false;
 			$args['pad_counts']   = false;
 		}
 		// 'parent' overrides 'child_of'.
-		if ( 0 < intval( $args['parent'] ) ) {
+		if ( 0 < (int) $args['parent'] ) {
 			$args['child_of'] = false;
 		}
 		if ( 'all' === $args['get'] ) {
 			$args['childless']    = false;
 				$excluded_children = array_merge(
 					$excluded_children,
 					(array) get_terms(
 						array(
 							'taxonomy'   => reset( $taxonomies ),
-							'child_of'   => intval( $extrunk ),
+							'child_of'   => (int) $extrunk,
 							'fields'     => 'ids',
 							'hide_empty' => 0,
 						)
 					)
 				);
 		$this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}";
 		$this->terms = null;
 		/**
-		 * Filter the terms array before the query takes place.
+		 * Filters the terms array before the query takes place.
 		 *
-		 * Return a non-null value to bypass WordPress's default term queries.
+		 * Return a non-null value to bypass WordPress' default term queries.
 		 *
 		 * @since 5.3.0
 		 *
 		 * @param array|null    $terms Return an array of term data to short-circuit WP's term query,
 		 *                             or null to allow WP queries to run normally.
-		 * @param WP_Term_Query $this  The WP_Term_Query instance, passed by reference.
+		 * @param WP_Term_Query $query The WP_Term_Query instance, passed by reference.
 		 */
 		$this->terms = apply_filters_ref_array( 'terms_pre_query', array( $this->terms, &$this ) );
 		if ( null !== $this->terms ) {
 			return $this->terms;

changeset 18	be944660c56a
parent 16	a86126ab1dd4
child 19	3d72ae0968f4