get_term( int|WP_Term|object $term, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' )

Get all Term data from database by Term ID.


Description Description

The usage of the get_term function is to apply filters to a term object. It is possible to get a term object from the database before applying the filters.

$term ID must be part of $taxonomy, to get from the database. Failure, might be able to be captured by the hooks. Failure would be the same value as $wpdb returns for the get_row method.

There are two hooks, one is specifically for each term, named ‘get_term’, and the second is for the taxonomy name, ‘term_$taxonomy’. Both hooks gets the term object, and the taxonomy name as parameters. Both hooks are expected to return a Term object.

‘get_term’ hook – Takes two parameters the term Object and the taxonomy name. Must return term object. Used in get_term() as a catch-all filter for every $term.

‘get_$taxonomy’ hook – Takes two parameters the term Object and the taxonomy name. Must return term object. $taxonomy will be the taxonomy name, so for example, if ‘category’, it would be ‘get_category’ as the filter name. Useful for custom taxonomies or plugging into default taxonomies.

See also See also


Top ↑

Parameters Parameters

$term

(int|WP_Term|object) (Required) If integer, term data will be fetched from the database, or from the cache if available. If stdClass object (as in the results of a database query), will apply filters and return a WP_Term object corresponding to the $term data. If WP_Term, will return $term.

$taxonomy

(string) (Optional) Taxonomy name that $term is part of.

Default value: ''

$output

(string) (Optional) The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a WP_Term object, an associative array, or a numeric array, respectively.

Default value: OBJECT

$filter

(string) (Optional) default is raw or no WordPress defined filter will applied.

Default value: 'raw'


Top ↑

Return Return

(array|WP_Term|WP_Error|null) Object of the type specified by $output on success. When $output is 'OBJECT', a WP_Term instance is returned. If taxonomy does not exist, a WP_Error is returned. Returns null for miscellaneous failure.


Top ↑

Source Source

File: wp-includes/taxonomy.php

815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
    if ( empty( $term ) ) {
        return new WP_Error( 'invalid_term', __( 'Empty Term.' ) );
    }
 
    if ( $taxonomy && ! taxonomy_exists( $taxonomy ) ) {
        return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
    }
 
    if ( $term instanceof WP_Term ) {
        $_term = $term;
    } elseif ( is_object( $term ) ) {
        if ( empty( $term->filter ) || 'raw' === $term->filter ) {
            $_term = sanitize_term( $term, $taxonomy, 'raw' );
            $_term = new WP_Term( $_term );
        } else {
            $_term = WP_Term::get_instance( $term->term_id );
        }
    } else {
        $_term = WP_Term::get_instance( $term, $taxonomy );
    }
 
    if ( is_wp_error( $_term ) ) {
        return $_term;
    } elseif ( ! $_term ) {
        return null;
    }
 
    // Ensure for filters that this is not empty.
    $taxonomy = $_term->taxonomy;
 
    /**
     * Filters a taxonomy term object.
     *
     * @since 2.3.0
     * @since 4.4.0 `$_term` is now a `WP_Term` object.
     *
     * @param WP_Term $_term    Term object.
     * @param string  $taxonomy The taxonomy slug.
     */
    $_term = apply_filters( 'get_term', $_term, $taxonomy );
 
    /**
     * Filters a taxonomy term object.
     *
     * The dynamic portion of the filter name, `$taxonomy`, refers
     * to the slug of the term's taxonomy.
     *
     * @since 2.3.0
     * @since 4.4.0 `$_term` is now a `WP_Term` object.
     *
     * @param WP_Term $_term    Term object.
     * @param string  $taxonomy The taxonomy slug.
     */
    $_term = apply_filters( "get_{$taxonomy}", $_term, $taxonomy );
 
    // Bail if a filter callback has changed the type of the `$_term` object.
    if ( ! ( $_term instanceof WP_Term ) ) {
        return $_term;
    }
 
    // Sanitize term, according to the specified filter.
    $_term->filter( $filter );
 
    if ( $output == ARRAY_A ) {
        return $_term->to_array();
    } elseif ( $output == ARRAY_N ) {
        return array_values( $_term->to_array() );
    }
 
    return $_term;
}

Top ↑

Changelog Changelog

Changelog
Version Description
4.4.0 Converted to return a WP_Term object if $output is OBJECT. The $taxonomy parameter was made optional.
2.3.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    Examples
    Get Term offers some handy information, but unfortunately lacks a link value.

    1
    $term = get_term( $term_id, $taxonomy );

    Gives you term slug: e.g.: term-slug-example

    1
    $slug = $term->slug;

    Gives you term name: e.g. Term Name Example

    1
    $name = $term->name;

    Gives you term description: e.g. This is my new cool custom term.

    1
    $desc = $term->description;
  2. Skip to note 2 content

    get_term() utilizes the WP Object Cache to store previously-fetched term data. This helps avoid subsequent data I/O calls from the database to read term data. For example:

    1
    2
    3
    4
    $term = get_term( 1 , 'store' );
    echo $term->name;
    $term = get_term( 1 , ' store' );
    echo $term->slug;

    This overly-simple example will only perform a single select query on the database. The second get_term will use the WP Object Cache to fetch the previous term object from memory.

You must log in before being able to contribute a note or feedback.