From 1eaf38088f65148dae955d47146d5f6057537aa8 Mon Sep 17 00:00:00 2001 From: Boone Gorges Date: Wed, 8 Jun 2016 04:07:47 +0000 Subject: [PATCH] Add a note about uniqueness to the doc block for `get_term_by()`. `get_term_by()` always returns a single term, even when more than one term matches the query parameters. The new note warns developers to use `get_terms()` when such ambiguity may result. Fixes #36878. git-svn-id: https://develop.svn.wordpress.org/trunk@37656 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/taxonomy.php | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index 47633d1f02..a51658fe11 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -902,6 +902,13 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) { * If $value does not exist, the return value will be false. If $taxonomy exists * and $field and $value combinations exist, the Term will be returned. * + * This function will always return the first term that matches the `$field`- + * `$value`-`$taxonomy` combination specified in the parameters. If your query + * is likely to match more than one term (as is likely to be the case when + * `$field` is 'name', for example), consider using get_terms() instead; that + * way, you will get all matching terms, and can provide your own logic for + * deciding which one was intended. + * * @todo Better formatting for DocBlock. * * @since 2.3.0