sanitize_term_field

Подготавливает (очищает) значение поля термина (рубрики) для его использования в тексте или где-то еще (зависит от контекста очистки).

Переданное в эту функцию значение любого поля, описывающего термин, будет подготовлено для использования этого значения в тексте.

Если будет передано значение несоответствующее контексту термина, то будет применен фильтр по умолчанию: term_{$field} затем {$taxonomy}_{$field}.

В этой функции достаточно много фильтров, чтобы не создавать свою, отдельную функции фильтрации, а использовать уже имеющиеся фильтры, подключаясь к фильтрам через хуки (см. код функции).

Хуки из функции:
(taxonomy)_(field)
(taxonomy)_(field)_rss
edit_(taxonomy)_(field)
edit_term_(field)
pre_(taxonomy)_(field)
pre_category_nicename
pre_term_(field)
term_(field)
term_(field)_rss
Возвращает

отфильтрованное поле, разные значения, зависит от переданного поля.

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

<?php sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ); ?>
$field(строка) (обязательный)
Название поля термина. Например: parent, term_id, count и т.д.
По умолчанию: нет
$value(строка) (обязательный)
Значение поля, указного в $field. Это значение будет очищаться, фильтроваться.
По умолчанию: нет
$term_id(число) (обязательный)
ID термина.
По умолчанию: нет
$taxonomy(строка) (обязательный)
Название таксономии, к которой принадлежит термин.
По умолчанию: нет
$context(строка) (обязательный)

Тип фильтрации. Одно из значений:

  • display – для вывода на экран
  • raw – просто вернет значение
  • edit – фильтр esc_html() если это поле description, и фильтр esc_attr() если другое поле.
  • db
  • slug
  • rss
  • attribute – фильтр esc_attr()
  • js – фильтр esc_js()

По умолчанию: ‘display’

Примеры

#1. Пример базовой функции ВП get_term_field(), в которой результат фильтруется через sanitize_term_field():

function get_term_field( $field, $term, $taxonomy, $context = 'display' ) {
	$term = (int) $term;
	$term = get_term( $term, $taxonomy );
	if ( is_wp_error($term) )
		return $term;

	if ( !is_object($term) )
		return '';

	if ( !isset($term->$field) )
		return '';

	return sanitize_term_field($field, $term->$field, $term->term_id, $taxonomy, $context);
}

Код из


wp-includes/taxonomy.php

WP 4.7.2

<?php
function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
	$int_fields = array( 'parent', 'term_id', 'count', 'term_group', 'term_taxonomy_id', 'object_id' );
	if ( in_array( $field, $int_fields ) ) {
		$value = (int) $value;
		if ( $value < 0 )
			$value = 0;
	}

	if ( 'raw' == $context )
		return $value;

	if ( 'edit' == $context ) {

		/**
		 * Filters a term field to edit before it is sanitized.
		 *
		 * The dynamic portion of the filter name, `$field`, refers to the term field.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed $value     Value of the term field.
		 * @param int   $term_id   Term ID.
		 * @param string $taxonomy Taxonomy slug.
		 */
		$value = apply_filters( "edit_term_{$field}", $value, $term_id, $taxonomy );

		/**
		 * Filters the taxonomy field to edit before it is sanitized.
		 *
		 * The dynamic portions of the filter name, `$taxonomy` and `$field`, refer
		 * to the taxonomy slug and taxonomy field, respectively.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed $value   Value of the taxonomy field to edit.
		 * @param int   $term_id Term ID.
		 */
		$value = apply_filters( "edit_{$taxonomy}_{$field}", $value, $term_id );

		if ( 'description' == $field )
			$value = esc_html($value); // textarea_escaped
		else
			$value = esc_attr($value);
	} elseif ( 'db' == $context ) {

		/**
		 * Filters a term field value before it is sanitized.
		 *
		 * The dynamic portion of the filter name, `$field`, refers to the term field.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed  $value    Value of the term field.
		 * @param string $taxonomy Taxonomy slug.
		 */
		$value = apply_filters( "pre_term_{$field}", $value, $taxonomy );

		/**
		 * Filters a taxonomy field before it is sanitized.
		 *
		 * The dynamic portions of the filter name, `$taxonomy` and `$field`, refer
		 * to the taxonomy slug and field name, respectively.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed $value Value of the taxonomy field.
		 */
		$value = apply_filters( "pre_{$taxonomy}_{$field}", $value );

		// Back compat filters
		if ( 'slug' == $field ) {
			/**
			 * Filters the category nicename before it is sanitized.
			 *
			 * Use the {@see 'pre_$taxonomy_$field'} hook instead.
			 *
			 * @since 2.0.3
			 *
			 * @param string $value The category nicename.
			 */
			$value = apply_filters( 'pre_category_nicename', $value );
		}

	} elseif ( 'rss' == $context ) {

		/**
		 * Filters the term field for use in RSS.
		 *
		 * The dynamic portion of the filter name, `$field`, refers to the term field.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed  $value    Value of the term field.
		 * @param string $taxonomy Taxonomy slug.
		 */
		$value = apply_filters( "term_{$field}_rss", $value, $taxonomy );

		/**
		 * Filters the taxonomy field for use in RSS.
		 *
		 * The dynamic portions of the hook name, `$taxonomy`, and `$field`, refer
		 * to the taxonomy slug and field name, respectively.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed $value Value of the taxonomy field.
		 */
		$value = apply_filters( "{$taxonomy}_{$field}_rss", $value );
	} else {
		// Use display filters by default.

		/**
		 * Filters the term field sanitized for display.
		 *
		 * The dynamic portion of the filter name, `$field`, refers to the term field name.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed  $value    Value of the term field.
		 * @param int    $term_id  Term ID.
		 * @param string $taxonomy Taxonomy slug.
		 * @param string $context  Context to retrieve the term field value.
		 */
		$value = apply_filters( "term_{$field}", $value, $term_id, $taxonomy, $context );

		/**
		 * Filters the taxonomy field sanitized for display.
		 *
		 * The dynamic portions of the filter name, `$taxonomy`, and `$field`, refer
		 * to the taxonomy slug and taxonomy field, respectively.
		 *
		 * @since 2.3.0
		 *
		 * @param mixed  $value   Value of the taxonomy field.
		 * @param int    $term_id Term ID.
		 * @param string $context Context to retrieve the taxonomy field value.
		 */
		$value = apply_filters( "{$taxonomy}_{$field}", $value, $term_id, $context );
	}

	if ( 'attribute' == $context ) {
		$value = esc_attr($value);
	} elseif ( 'js' == $context ) {
		$value = esc_js($value);
	}
	return $value;
}