Функция term_exists() в WordPress: использование, производительность, хуки

# TERM_EXISTS() │ WP 3.0.0

Функция term_exists() проверяет, существует ли заданный элемент таксономии. Она возвращает либо идентификатор термина, либо данные о термине, если элемент (термин) существует.

## Разработка функции

Ранее она именовалась is_term(), которая была представлена в версии 2.3.0.

С версии WP 6.0 функция работает с объектным кэшем и использует get_terms(). 

### Производительность до WP 6.0

До версии 6.0 функция запускала запрос к базе данных. Для этой цели также можно использовать get_term_by(), который использует кэш терминов.

#### Используется в

- category_exists()
- tag_exists()
- wp_remove_object_terms()

### Время выполнения

- 1 раз — 0.000419 сек (быстро)
- 50000 раз — 14.74 сек (медленно)
- PHP 7.0.14, WP 4.7

## Хуки функции

Функция использует хук term_exists_default_query_args.

## Возвращаемые значения

Функция может вернуть несколько значений:

- **Строка** — идентификатор термина в виде строки, если таксономия не указана и термин существует.
  - Пример: term_exists( 395 ) возвращает строку "395".

- **Массив** — когда указана таксономия и термин существует:
  ```json
  {
    "term_id": "идентификатор термина",
    "term_taxonomy_id": "идентификатор таксономии"
  }

• null — есл�� термин не существует.

• 0 — если передано 0 вместо идентификатора термина.

Использование

Синтаксис функции:

term_exists( $term, $taxonomy, $parent_term );

Параметры функции

• $term (string|int) (обязательный) — термин, который вы хотите проверить. Можно указать название, альтернативное название (slug) или идентификатор.

  Важно: Если указан идентификатор, оно должно быть числовым, а не строковым. Например, используйте 12, а не '12'.

• $taxonomy (string) — название таксономии, с которой будет работать функция. Необязательно указывать, если в параметре $term передан идентификатор термина.

  По умолчанию: ''

• $parent_term (string|int) — идентификатор родительского термина, под которым предполагается поиск элемента таксономии.

  По умолчанию: null

Примеры

Пример 1: Проверка существования термина (в любой таксономии)

$term = term_exists( 'miscellaneous' );
// возвращает идентификатор таксономического элемента с slug 'miscellaneous'

$term = term_exists( 'Men Clothes' );
// возвращает идентификатор таксономического элемента с названием 'Men Clothes'

Пример 2: Проверка существования термина в конкретной таксономии

Проверим, существует ли термин в таксономии my_tax:

$term = term_exists( 'Men clothing', 'my_tax' );
// возвращает массив
//    [
//        'term_id' => 80,
//        'term_taxonomy_id' => 84
//    ]

// Идентификатор элемента таксономии
echo $term['term_id'];

// Идентификатор элемента таксономии в структуре таксономии
echo $term['term_taxonomy_id'];

Проверим, существует ли категория "Uncategorized":

$term = term_exists( 'Uncategorized', 'category' );

if ( $term !== 0 && $term !== null ) {
    echo 'Категория Uncategorized существует!';
}

Пример 3: Кэширование начиная с WP 6.0

С WP 6.0 функция term_exists() использует кэш. Для обеспечения получения некэшированного результата есть два способа:

1. Использование нового фильтра term_exists_default_query_args:

   $callback = function ( $args ) {
     $args['cache_domain'] = microtime();
   };
   
   add_filter( 'term_exists_default_query_args', $callback );
   
   $check = term_exists( 123, 'category' );
   
   remove_filter( 'term_exists_default_query_args', $callback );

2. Использование wp_suspend_cache_invalidation():

   wp_suspend_cache_invalidation( true );
   
   $check = term_exists( 123, 'category' );
   
   wp_suspend_cache_invalidation( false );

Примечания

• Глобальная переменная: $_wp_suspend_cache_invalidation, принимает true или false.

Изменения

• С версии 3.0.0 — введена
• С версии 6.0.0 — преобразована для использования get_terms().

Код функции TERM_EXISTS()

function term_exists( $term, $taxonomy = '', $parent_term = null ) {
    global $_wp_suspend_cache_invalidation;

    if ( null === $term ) {
        return null;
    }

    $defaults = array(
        'get'                    => 'all',
        'fields'                 => 'ids',
        'number'                 => 1,
        'update_term_meta_cache' => false,
        'order'                  => 'ASC',
        'orderby'                => 'term_id',
        'suppress_filter'        => true,
    );

    // Убедитесь, что запросы не кэшируются при импорте.
    if ( ! empty( $_wp_suspend_cache_invalidation ) ) {
        $defaults['cache_results'] = false;
    }

    if ( ! empty( $taxonomy ) ) {
        $defaults['taxonomy'] = $taxonomy;
        $defaults['fields']   = 'all';
    }

    $defaults = apply_filters( 'term_exists_default_query_args', $defaults, $term, $taxonomy, $parent_term );

    if ( is_int( $term ) ) {
        if ( 0 === $term ) {
            return 0;
        }
        $args  = wp_parse_args( array( 'include' => array( $term ) ), $defaults );
        $terms = get_terms( $args );
    } else {
        $term = trim( wp_unslash( $term ) );
        if ( '' === $term ) {
            return null;
        }

        if ( ! empty( $taxonomy ) && is_numeric( $parent_term ) ) {
            $defaults['parent'] = (int) $parent_term;
        }

        $args  = wp_parse_args( array( 'slug' => sanitize_title( $term ) ), $defaults );
        $terms = get_terms( $args );
        if ( empty( $terms ) || is_wp_error( $terms ) ) {
            $args  = wp_parse_args( array( 'name' => $term ), $defaults );
            $terms = get_terms( $args );
        }
    }

    if ( empty( $terms ) || is_wp_error( $terms ) ) {
        return null;
    }

    $_term = array_shift( $terms );

    if ( ! empty( $taxonomy ) ) {
        return array(
            'term_id'          => (string) $_term->term_id,
            'term_taxonomy_id' => (string) $_term->term_taxonomy_id,
        );
    }

    return (string) $_term;
}

Связанные функции

Условные теги

• cat_is_ancestor_of()
• category_exists()
• comments_open()
• email_exists()
• has_block()
• has_category()
• И другие!

Таксономии: Категории, теги и пр.

• edit_term_link()
• get_edit_term_link()
• get_taxonomies()
• get_taxonomy()
• И другие!