get_terms( array|string $args = array() )
Retourne les termes pour une taxonomie donnée ou une liste de taxonomies.
Description
On peut complètement personnaliser la requête en remplissant les champs du tableau $args, autant que contrôler la sortie avec un filtre.
Le filtre 'get_terms' sera appelé si des termes sont trouvés dans le cache.
Paramètre
$args(array | string) (Optionnel) Tableau ou chaîne d'arguments. Liste des arguments acceptés :
'taxonomy'
(string | array) Noms des taxonomies associées aux termes recherchés.'object_ids'
(int | array) ID d'un objet (ex : poste) ou tableau d'ID d'objets. Les résultats seront limités par les termes associés à ces objets.'orderby'
(string) Champ pour ordonner les termes par :- Champs d'un objet terme : 'name', 'slug', 'term_group', 'term_id', 'id', 'description', 'parent', 'term_order'. Sauf si $object_ids n'est pas vide, 'term_order' est traité comme 'term_id'.
- 'count' pour utiliser le nombre d'objets associés avec le terme.
- 'include' pour correspondre avec 'order' du paramètre $include.
- 'slug__in' pour correspondre avec 'order' du paramètre $slug.
- 'meta_value', 'meta_value_num'.
- La valeur de $meta_key.
- Le tableau de clés de $meta_query.
- 'none' pour omettre la clause ORDER BY.
- Par défaut : 'name'.
'order'
(string) Pour que l'ordre des termes soit ascendant ('ASC') ou descendant ('DESC').
Par défaut : 'ASC'.'hide_empty'
(bool | int) Si réglé à false, retourne en plus les termes assignés à aucuns postes.
Par défaut : true.'include'
(array | string) Tableau d'ID des termes à inclure. Sous forme d'une chaîne, les ID doivent être séparés par des virgules suivies d'un espace.
Par défaut : array().'exclude'
(array | string) Tableau ou chaîne d'ID des termes à exclure. Si $include n'est pas vide, $exclude est ignoré.
Par défaut : array().'exclude_tree'
(array | string) Tableau ou chaîne d'ID des termes à exclure ainsi que leurs termes enfants. Si $include n'est pas vide, $exclude_tree est ignoré.
Par défaut : array().'number'
(int | string) Maximum de termes à retourner. Accepte '' | 0 et plus.
Par défaut : 0 (tous les termes).'offset'
(int) Nombre à partir duquel les termes seront retournés.'fields'
(string) Gère les champs des termes retournés. Accepte :- 'all' retourne un tableau d'objets WP_Term complets.
- 'all_with_object_id' retourne un tableau d'objets WP_Term avec le paramètre 'object_id'. Fonctionne seulement si le paramètre $object_ids est généré.
- 'ids' retourne un tableau d'ID de terme (int[]).
- 'tt_ids' retourne un tableau d'ID de taxonomie de terme (int[]).
- 'names' retourne un tableau de noms des termes (string[]).
- 'slugs' retourne un tableau de slugs des termes (string[]).
- 'count' retourne le nombre de termes correspondants (int).
- 'id=>parent' retourne un tableau associatif ID terme => ID parent (array).
- 'id=>name' retourne un tableau associatif ID terme => nom terme (array).
- 'id=>slug' retourne un tableau associatif ID terme => slug terme (array).
- Par défaut : 'all'.
'count'
(bool) Si $count vaut true, la requête retournera le nombre de termes trouvés et aura la priorité sur $fields.Par défaut : false.'name'
(string | array) retournera un nom ou un tableau de noms de termes.'slug'
(string | array) retournera un slug ou un tableau de slugs de termes.'term_taxonomy_id'
(int | array) retournera une ID de taxonomy ou un tableau d'ID de taxonomies associées aux termes.'hierarchical'
(bool) Si réglé à false, la requête inclura les termes qui ont des descendants non vide (même si $hide_empty est à true).
Par défaut : true.'search'
(string) Critères de recherche pour correspondre aux termes. La chaîne sera formattée en SQL.'name__like'
(string) Retournera les termes dont le nom commence par $name__like.'description__like'
(string) Retournera les termes dont la description commence par $description__like.'pad_counts'
(bool) Allonge la quantité des objets (ex : postes) associés à un terme à la quantité des objets de termes enfants.
Par défaut : false.'get'
(string) Si réglé à 'all', retourne tous les termes indépendamment des termes parents et des termes vides.
Par défaut : '''child_of'
(int) ID du terme pour recevoir ses termes enfants. Si plusieurs taxonomies sont passées $child_of est ignoré.
Par défaut : 0.'parent'
(int | string) ID du terme parent pour recevoir ses enfants directs.'childless'
(bool) True pour limiter les résultats aux termes qui n'ont pas d'enfants. Ce paramètre n'a pas d'effets sur les taxonomies non hiérarchiques.
Par défaut : false.'cache_domain'
(string) Clé unique du cache produit quand la requête est stockée dans le cache d'un objet.
Par défaut : 'core''update_term_meta_cache'
(bool) Amorce le cache des métas des termes correspondants.
Par défaut : true.'meta_query'
(array) Limite le résultats en ajoutant une clause meta à la requête.
Voir la classWP_Meta_Query.'meta_key'
(string) Limite les termes qui correspondent à une clé de métadonnée spécifique. Peut être utilisé en conjonction avec $meta_value.'meta_value'
(string) Limite les termes qui correspondent à une valeur de métadonnée spécifique. Habituellement utilisé en conjonction avec $meta_key.'meta_type'
(string) Type (format MySQL) de $meta_value.'meta_compare'
(string) Opérateur de comparaison sur $meta_value.
Valeur par défaut : array()
Retourne
(array | int | WP_Error) Tableau d'instances de l'objet WP_Term, un compte de celles-ci ou l'objet WP_Error si aucunes taxonomies n'existent.
Structure de la fonction get_terms()
Définie dans le fichier wp-includes/taxonomy.php à la ligne 1180 :
function get_terms( $args = array(), $deprecated = '' ) {
$term_query = new WP_Term_Query();
$defaults = array(
'suppress_filter' => false,
);
/*
* Legacy argument format ($taxonomy, $args) takes precedence.
*
* We detect legacy argument format by checking if
* (a) a second non-empty parameter is passed, or
* (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies)
*/
$_args = wp_parse_args( $args );
$key_intersect = array_intersect_key( $term_query->query_var_defaults, (array) $_args );
$do_legacy_args = $deprecated || empty( $key_intersect );
if ( $do_legacy_args ) {
$taxonomies = (array) $args;
$args = wp_parse_args( $deprecated, $defaults );
$args['taxonomy'] = $taxonomies;
} else {
$args = wp_parse_args( $args, $defaults );
if ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) {
$args['taxonomy'] = (array) $args['taxonomy'];
}
}
if ( ! empty( $args['taxonomy'] ) ) {
foreach ( $args['taxonomy'] as $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
}
}
// Don't pass suppress_filter to WP_Term_Query.
$suppress_filter = $args['suppress_filter'];
unset( $args['suppress_filter'] );
$terms = $term_query->query( $args );
// Count queries are not filtered, for legacy reasons.
if ( ! is_array( $terms ) ) {
return $terms;
}
if ( $suppress_filter ) {
return $terms;
}
/**
* Filters the found terms.
*
* @since 2.3.0
* @since 4.6.0 Added the `$term_query` parameter.
*
* @param array $terms Array of found terms.
* @param array $taxonomies An array of taxonomies.
* @param array $args An array of get_terms() arguments.
* @param WP_Term_Query $term_query The WP_Term_Query object.
*/
return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query );
}
Fonctions et Hook utilisés par get_terms()
__()Retourne la traduction d'un texte.
wp_parse_args()Fusionne des arguments définis par l'utilisateur dans un tableau par défaut.
get_termsFiltre les terme trouvés.
taxonomy_exists()Détermine si un nom de taxonomie existe.
apply_filters()Appel les fonctions qui ont été attaché à un filtre (hook).
Où trouver la fonction get_terms()
dans le CMS Wordpress
Exemples
$arguments__termes_defaut = array (
'taxonomy' => 'category', //empty string(''), false, 0 don't work, and return empty array
'orderby' => 'name',
'order' => 'ASC',
'hide_empty' => true, //can be 1, '1' too
'include' => 'all', //empty string(''), false, 0 don't work, and return empty array
'exclude' => 'all', //empty string(''), false, 0 don't work, and return empty array
'exclude_tree' => 'all', //empty string(''), false, 0 don't work, and return empty array
'number' => false, //can be 0, '0', '' too
'offset' => '',
'fields' => 'all',
'name' => '',
'slug' => '',
'hierarchical' => true, //can be 1, '1' too
'search' => '',
'name__like' => '',
'description__like' => '',
'pad_counts' => false, //can be 0, '0', '' too
'get' => '',
'child_of' => false, //can be 0, '0', '' too
'childless' => false,
'cache_domain' => 'core',
'update_term_meta_cache' => true, //can be 1, '1' too
'meta_query' => '',
'meta_key' => array(),
'meta_value'=> '',
);$terms = get_terms( array(
'taxonomy' => 'tax_name',
'parent' => 0
) );$taxonomies = get_terms( array(
'taxonomy' => 'taxonomy_name',
'hide_empty' => false
) );
if ( !empty($taxonomies) ) :
$output = '<select>';
foreach( $taxonomies as $category ) {
if( $category->parent == 0 ) {
$output.= '<optgroup label="'. esc_attr( $category->name ) .'">';
foreach( $taxonomies as $subcategory ) {
if( $subcategory->parent == $category->term_id ) {
$output.= '<option value="'. esc_attr( $subcategory->term_id ) .'">'
. esc_html( $subcategory->name ) .'</option>';
}
}
$output.='</optgroup>';
}
}
$output.='</select>';
echo $output;
endif;$terms = get_terms( array(
'taxonomy' => 'tax_slug',
'hide_empty' => false,
'meta_query' => array(
array(
'key' => 'meta_key_slug_1',
'value' => 'desired value to look for'
)
),
'meta_key' => 'meta_key_slug_2',
'orderby' => 'meta_key_slug_2'
) );Sources
Codex Wordpress : get_terms()
Autres fonctions dans le même fichier : wp-includes/taxonomy.php