Функция sanitize_term() в WordPress с примерами

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

Основные особенности:

• Функция обрабатывает каждое поле термина с учетом контекста.
• Поддерживает различные контексты, такие как отображение данных, работа с JavaScript, база данных и другие.
• Автоматически удаляет поля, которые не соответствуют допустимым полям термина.

array|object sanitize_term( array|object $term, string $taxonomy, string $context = 'display' )

Параметры

• $term (массив или объект, обязательный): Данные термина, которые нужно очистить. Это может быть массив или объект, содержащий поля термина, такие как name, slug, description и т.д.
• $taxonomy (строка, обязательный): Название таксономии, к которой принадлежит термин, например, 'category' или 'post_tag'.
• $context (строка, необязательный): Контекст, в котором нужно очистить поля термина. Возможные значения: 'raw', 'edit', 'db', 'display', 'rss', 'attribute', 'js'. По умолчанию — 'display'.

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

• Массив или объект: Возвращает массив или объект с очищенными полями термина. Все значения фильтруются в соответствии с контекстом, а недопустимые поля удаляются.

Контексты использования

• raw: Возвращает необработанные данные термина.
• display: Очищает данные для безопасного вывода на экран (используется по умолчанию).
• edit: Очищает данные для формы редактирования (применяются фильтры esc_html() и esc_attr()).
• db: Очищает данные для сохранения в базу данных.
• attribute: Применяет фильтр esc_attr() для безопасного использования в HTML-атрибутах.
• js: Применяет фильтр esc_js() для безопасного использования данных в JavaScript.
• rss: Очищает данные для использования в RSS-лентах.

Пример 1: Очистка пользовательского термина для RSS

Функция sanitize_term() может быть полезна для подготовки термина перед публикацией в RSS-ленте. Например, если у вас есть пользовательская таксономия для продуктов, можно очистить ее для корректного отображения в RSS.

$product_term = array(
    'term_id'          => 12,
    'name'             => 'Продукт "A"',
    'slug'             => 'produkt-a',
    'description'      => 'Описание продукта "A" с HTML <strong>тегами</strong>',
    'parent'           => 0,
    'count'            => 15,
);

$sanitized_product_term = sanitize_term( $product_term, 'product_category', 'rss' );

print_r( $sanitized_product_term );

Результат:

Array
(
    [term_id] => 12
    [name] => Продукт "A"
    [slug] => produkt-a
    [description] => Описание продукта "A" с HTML <strong>тегами</strong>
    [parent] => 0
    [count] => 15
    [filter] => rss
)

Пример 2: Очистка термина для использования в атрибутах HTML

Этот пример демонстрирует, как очистить поля термина для безопасного использования в HTML-атрибутах, например, в data-* атрибутах или в значениях id или class.

$custom_term = array(
    'term_id'          => 7,
    'name'             => 'Специальный & Term',
    'slug'             => 'special-term',
    'description'      => 'Тестовое описание для атрибутов',
    'parent'           => 0,
    'count'            => 5,
);

$sanitized_term_attr = sanitize_term( $custom_term, 'custom_taxonomy', 'attribute' );

print_r( $sanitized_term_attr );

Результат:

Array
(
    [term_id] => 7
    [name] => Специальный & Term
    [slug] => special-term
    [description] => Тестовое описание для атрибутов
    [parent] => 0
    [count] => 5
    [filter] => attribute
)

Пример 3: Очистка термина перед сохранением в базу данных

Когда вы создаете или редактируете термины, важно правильно обработать их данные перед сохранением в базу данных, чтобы избежать проблем с безопасностью или некорректным форматированием данных.

$new_term = array(
    'term_id'          => 25,
    'name'             => 'Новый Термин',
    'slug'             => 'noviy-termin',
    'description'      => 'Описание нового термина с потенциальными уязвимостями',
    'parent'           => 2,
    'count'            => 0,
);

$sanitized_term_db = sanitize_term( $new_term, 'category', 'db' );

print_r( $sanitized_term_db );

Результат:

Array
(
    [term_id] => 25
    [name] => Новый Термин
    [slug] => noviy-termin
    [description] => Описание нового термина с потенциальными уязвимостями
    [parent] => 2
    [count] => 0
    [filter] => db
)

Пример 4: Очистка термина для использования в JavaScript

Этот пример показывает, как подготовить данные термина для безопасного использования в скриптах JavaScript, например, при передаче данных в переменные JavaScript на фронтенде.

$js_term = array(
    'term_id'          => 9,
    'name'             => 'Тестовый JS-Термин',
    'slug'             => 'js-test-term',
    'description'      => 'Описание с потенциально опасными символами: " \' < > &',
    'parent'           => 0,
    'count'            => 8,
);

$sanitized_term_js = sanitize_term( $js_term, 'tag', 'js' );

print_r( $sanitized_term_js );

Результат:

Array
(
    [term_id] => 9
    [name] => Тестовый JS-Термин
    [slug] => js-test-term
    [description] => Описание с потенциально опасными символами: \" \' < > &
    [parent] => 0
    [count] => 8
    [filter] => js
)

Пример 5: Очистка термина без изменения данных (context: raw)

Иногда вам может потребоваться просто вернуть оригинальные данные термина без какой-либо очистки, что может быть полезно, например, для внутреннего использования или при повторной обработке.

$raw_term = array(
    'term_id'          => 10,
    'name'             => 'Сырой Термин',
    'slug'             => 'raw-term',
    'description'      => 'Описание сырого термина, без фильтрации',
    'parent'           => 1,
    'count'            => 3,
);

$sanitized_term_raw = sanitize_term( $raw_term, 'custom_taxonomy', 'raw' );

print_r( $sanitized_term_raw );

Результат:

Array
(
    [term_id] => 10
    [name] => Сырой Термин
    [slug] => raw-term
    [description] => Описание сырого термина, без фильтрации
    [parent] => 1
    [count] => 3
    [filter] => raw
)

Заключение

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