[wp-trac] [WordPress Trac] #35381: Introduce `WP_Term_Query`

[WordPress Trac]

#35381: Introduce `WP_Term_Query`
-------------------------------------------------+-------------------------
 Reporter:  boonebgorges                         |       Owner:
     Type:  defect (bug)                         |      Status:  new
 Priority:  normal                               |   Milestone:  Future
Component:  Taxonomy                             |  Release
 Severity:  normal                               |     Version:
 Keywords:  has-patch needs-testing dev-         |  Resolution:
  feedback                                       |     Focuses:
-------------------------------------------------+-------------------------
Changes (by flixos90):

 * keywords:  needs-patch => has-patch needs-testing dev-feedback


Comment:

 [attachment:35381.diff] is a first take on this class. I used a similar
 approach like the one we have been using for other more recent query
 classes (like `WP_Comment_Query` and now `WP_Site_Query`) where the main
 query only queries IDs and then uses `get_term()` to get objects. My goal
 for this first patch was to mimic the functionality of the `get_terms()`
 function. In a later iteration the class should also be able to be used by
 `wp_get_object_terms()` - it isn't yet, but this is just a note to keep in
 mind for further enhancement.

 Some details about the implementation:
 * Backwards compatibility is a major issue here: there were a number of
 filters in `get_terms()` that I have now moved into the class while also
 adding the usual actions and filters that we have in other query classes.
 My tests so far worked fine, but we should have a detailed look at all the
 filters and whether they work as intended. I also added a
 `$suppress_filters` argument which should probably (when active) disable
 more filters than it currently does in this implementation.
 * I left the check whether a taxonomy exists (possibly throws `WP_Error`)
 and whether there is a hierarchical taxonomy in `get_terms()`. I think
 both of them are not explicitly required to run for any term query.
 * I found a bug that is possible to happen even in current versions of
 WordPress. In version 4.5 we allowed to query terms of any taxonomy - in
 this case the `$taxonomy` argument is null. However there are multiple
 occassions where it is assumed to be an array. In all cases of a foreach
 loop, I added a check whether `$taxonomy` is a trueish value (in this case
 it's always an array). At one point there is a `reset()` call which
 obviously will throw a notice at this point if `$taxonomy` is null. Try
 the following query for example: `get_terms( array( 'name' =>
 'uncategorized' ) )`. We should remove the requirement for passing a
 taxonomy for other functions (since it's no longer necessary in a lot of
 cases since term splitting) - for this particular notice, we need to see
 if we can adjust `sanitize_term_field()`. Btw, this also makes the
 documentation slightly incorrect where `$taxonomy` is stated to always be
 an array.
 * Besides the `$suppress_filters` argument, I also added a `no_found_rows`
 argument (similar to other query classes) and a `$count` argument. The
 latter is already present through `$fields = 'count'`, but I thought we
 could standardize it, similar to the other query classes. It's a duplicate
 though, so if that is an issue, maybe we can deprecate `$fields = 'count'`
 - or otherwise get rid of `$count` again if there's no other way.
 * Another problem in my opinion is the `get_terms_fields` filter. Since
 this class always queries for IDs (or a count), using the
 `get_terms_fields` filter to modify the requested fields in any way will
 most probably mess up the query - it's basically not of any use at this
 point. I wonder if we can deprecate/drop it - it does not affect what the
 query returns anyway with this implementation.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/35381#comment:3>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform