`WP_Term_Query` already supports querying terms by 'slug', 'name', and 'term_taxonomy_id'. Its additional arguments allow us to generate nearly the same SQL queries as before.
This change has one yuge benefit: the term queries are now cached.
Add tests to increase coverage of `get_term_by()`.
Props spacedmonkey, boonebgorges, johnjamesjacoby, pento, ocean90.
Fixes#21760.
Built from https://develop.svn.wordpress.org/trunk@38677
git-svn-id: http://core.svn.wordpress.org/trunk@38620 1a063a9b-81f0-0310-95a4-ce76da25c4cd
The new 'object_ids' parameter for `WP_Term_Query` allows queries for
terms that "belong to" a given object. This change makes it possible
to use `WP_Term_Query` inside of `wp_get_object_terms()`, rather than
assembling a SQL query.
The refactor has a couple of benefits:
* Less redundancy.
* Better consistency in accepted arguments between the term query functions. See #31105.
* Less redundancy.
* Object term queries are now cached. The `get_object_term_cache()` cache remains, and will be a somewhat less fragile secondary cache in front of the query cache (which is subject to frequent invalidation).
* Less redundancy.
A small breaking change: Previously, if a non-hierarchical taxonomy had
terms that had a non-zero 'parent' (perhaps because of a direct SQL
query), `wp_get_object_terms()` would respect the 'parent' argument.
This is in contrast to `WP_Term_Query` and `get_terms()`, which have
always rejected 'parent' queries for non-hierarchical taxonomies. For
consistency, the behavior of `get_terms()` is being applied across the
board: passing 'parent' for a non-hierarchical taxonomy will result in
an empty result set (since the cached taxonomy hierarchy will be empty).
Props flixos90, boonebgorges.
See #37198.
Built from https://develop.svn.wordpress.org/trunk@38667
git-svn-id: http://core.svn.wordpress.org/trunk@38610 1a063a9b-81f0-0310-95a4-ce76da25c4cd
By adding the `$output` parameter to `get_attachment_taxonomies()`, the
function signature matches that of `get_object_taxonomies()`. The change
also allows for more consistent behavior when passing `output=objects`
to `get_object_taxonomies()` for the 'attachment' object type, since
the `$output` parameter is now passed through the function stack.
Props codemovement.pk.
See #37368.
Built from https://develop.svn.wordpress.org/trunk@38292
git-svn-id: http://core.svn.wordpress.org/trunk@38233 1a063a9b-81f0-0310-95a4-ce76da25c4cd
[37623] used the wrong parameter name (count=true instead of fields=count).
For greater flexibility and forward compatibility with other potential changes
to the return value of `get_terms()`, we now do a looser check: any non-array
value is excluded from the filter.
Fixes#36992.
Built from https://develop.svn.wordpress.org/trunk@37634
git-svn-id: http://core.svn.wordpress.org/trunk@37602 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Use of the 'get_terms' filter was consolidated in [37572], with the
introduction of `WP_Term_Query`. At that time, the result of 'count=true'
queries began being filtered by 'get_terms'. This breaks existing 'get_terms'
callbacks, which often assume that the returned value will be an array or a
`WP_Error` object.
Props JustinSainton.
Fixes#36992.
Built from https://develop.svn.wordpress.org/trunk@37623
git-svn-id: http://core.svn.wordpress.org/trunk@37591 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Prior to [37572], arguments passed to `get_terms()` were passed immediately
through `wp_parse_args()`, which made it possible to pass arguments as a
querystring (`hide_empty=0`) rather than an array
(`array( 'hide_empty' => false )`). [37572] moved default argument parsing
into `WP_Term_Query`, while assuming that arguments passed to `get_terms()`
would be formatted as an array.
To provide compatibility, we now parse all args passed to `get_terms()` into
an array before processing.
See #35381.
Built from https://develop.svn.wordpress.org/trunk@37599
git-svn-id: http://core.svn.wordpress.org/trunk@37567 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Since [37573], object relationship caches (`{$taxonomy}_relationships`)
contain term IDs rather than term objects. See #36814. As such, it's no longer
necessary to clear these caches when a term is updated; none of the data that's
changed on update (name, description, count, etc) is stored in the relationship
cache.
Fixes#36251.
Built from https://develop.svn.wordpress.org/trunk@37593
git-svn-id: http://core.svn.wordpress.org/trunk@37561 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Previously, objects containing all data about a term were stored in each
object's term cache. Besides being wasteful, this approach caused invalidation
issues, as when a modified term count required a flush for all objects
belonging to the term.
Backward compatibility is maintained for plugins that continue to put object
data directly into the `{$taxonomy}_relationships` cache bucket.
Fixes#36814.
Built from https://develop.svn.wordpress.org/trunk@37573
git-svn-id: http://core.svn.wordpress.org/trunk@37541 1a063a9b-81f0-0310-95a4-ce76da25c4cd
`WP_Term_Query` is modeled on existing query classes, such as those used
for comments and users. It provides a more consistent structure for generating
term queries, and should make it easier to add new functionality in the future.
Props flixos90, boonebgorges.
See #35381.
Built from https://develop.svn.wordpress.org/trunk@37572
git-svn-id: http://core.svn.wordpress.org/trunk@37540 1a063a9b-81f0-0310-95a4-ce76da25c4cd
[34529] introduced logic intended to prime the termmeta cache for certain
values of the `fields` parameter. There were a few bugs:
* The `all_with_object_id` param was misspelled.
* `term_id` was used instead of `ids`.
* The values being passed to `update_termmeta_cache()` in the case where `fields=ids` was not correct.
All of these would result in a failure to pre-fetch termmeta in some cases.
Props dlh.
Fixes#36932.
Built from https://develop.svn.wordpress.org/trunk@37567
git-svn-id: http://core.svn.wordpress.org/trunk@37535 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Also use 'back-compat' in some inline comments where backward compatibility is the subject and shorthand feels more natural.
Note: 'backwards compatibility/compatibile' can also be considered correct, though it's primary seen in regular use in British English.
Props ocean90.
Fixes#36835.
Built from https://develop.svn.wordpress.org/trunk@37431
git-svn-id: http://core.svn.wordpress.org/trunk@37397 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Known functions, classes, and methods are now auto-linked in Code Reference pages following #meta1483.
Note: Hook references are still linked via inline `@see` tags due to the unlikelihood of reliably matching for known hooks based on a RegEx pattern.
See #32246.
Built from https://develop.svn.wordpress.org/trunk@37342
git-svn-id: http://core.svn.wordpress.org/trunk@37308 1a063a9b-81f0-0310-95a4-ce76da25c4cd
The codex says that taxonomy names "should only contain lowercase letters and the underscore character", but that's not enforced. It's too late to enforce it, since some plugins haven't been following it and the official phpdoc doesn't mention this restriction.
Built from https://develop.svn.wordpress.org/trunk@37133
git-svn-id: http://core.svn.wordpress.org/trunk@37100 1a063a9b-81f0-0310-95a4-ce76da25c4cd
When querying for terms in hierarchical taxonomies, `get_terms()` initially
queries for all matching terms, and then trims the located results based on the
`$number` and `$offset` arguments passed to the function. See #8832. However,
a flaw in the original logic meant that results were failing to be trimmed
properly in cases where `$offset` exceeds the total number of matching terms;
in these cases, we should force an empty array.
Props danielbachhuber.
Fixes#35935.
Built from https://develop.svn.wordpress.org/trunk@36691
git-svn-id: http://core.svn.wordpress.org/trunk@36658 1a063a9b-81f0-0310-95a4-ce76da25c4cd
`get_terms()` has historically required that a taxonomy be specified when
querying terms. This requirement is related to the fact that terms could
formerly be shared between taxonomies, making `$taxonomies` critical for
disambiguation. Since terms can no longer be shared as of 4.4, it'
s desirable to be able to query for terms regardless of what taxonomy they're in.
Because it's now optional to pass taxonomies, it's no longer necessary to have
`$taxonomies` as the first (and required) parameter for `get_terms()`. The new
function signature is `get_terms( $args )`, where 'taxonomy' can (optionally) be
passed as part of the `$args` array. This syntax is more consistent with
functions like `get_users()` and `get_posts()`.
We've maintained backward compatibility by always giving precedence to the old
argument format. If a second parameter is detected, or if it's detected that
the first parameter is a list of taxonomy names rather than an `$args` array,
`get_terms()` will parse the function arguments in the legacy fashion.
Props flixos90, swissspidy, DrewAPicture, boonebgorges.
Fixes#35495.
Built from https://develop.svn.wordpress.org/trunk@36614
git-svn-id: http://core.svn.wordpress.org/trunk@36581 1a063a9b-81f0-0310-95a4-ce76da25c4cd
The `$orderby` parameter of `get_terms()` now accepts the following values,
related to term meta:
* 'meta_value'
* 'meta_value_num'
* the value of the `$meta_key` parameter
* any key from the `$meta_query` array
This brings order-by-meta support for terms in line with post, comment, and
user queries.
As a byproduct of these improvements, `$meta_key` and `$meta_value` parameters
have been introduced to `get_terms()`. They interact with `$meta_query` in the
same way as in `WP_Query` and other query classes.
Props jadpm, eherman24.
Fixes#34996.
Built from https://develop.svn.wordpress.org/trunk@36485
git-svn-id: http://core.svn.wordpress.org/trunk@36452 1a063a9b-81f0-0310-95a4-ce76da25c4cd
[32353] changed the way the 'name' param in `get_terms()` is sanitized, by
running it through `sanitize_term_field( 'name' )` before performing the SQL
query. An unintentional side effect of this change was that the string is
double-escaped: once by `wp_filter_kses()`, and once by `esc_sql()`. The
double-escaping was causing 'name' queries to fail when the param contained
apostrophes or other escaped characters.
Fixes#35493.
Built from https://develop.svn.wordpress.org/trunk@36348
git-svn-id: http://core.svn.wordpress.org/trunk@36315 1a063a9b-81f0-0310-95a4-ce76da25c4cd
[34999] modified the cache strategy for terms in the context of
`wp_get_object_terms()`. As part of these changes, the `object_id` property of
term objects had to be unset before being cached. To avoid modifying passed-by-
reference terms, `update_term_cache()` attempted to make a copy of the terms
passed to the function; however, it failed to use the `clone` keyword, and thus
only created a reference instead of a copy.
Props berengerzyla.
Fixes#35462.
Built from https://develop.svn.wordpress.org/trunk@36323
git-svn-id: http://core.svn.wordpress.org/trunk@36290 1a063a9b-81f0-0310-95a4-ce76da25c4cd
`array_slice()` must be told to preserve keys when the query results exceed the
limit specified the 'number' parameter, so that `id=>parent` and other
id-indexed return value formats don't get mangled.
Props fantasyworld, wpdelighter.
Fixes#35382.
Built from https://develop.svn.wordpress.org/trunk@36252
git-svn-id: http://core.svn.wordpress.org/trunk@36219 1a063a9b-81f0-0310-95a4-ce76da25c4cd
