Произвольные данные таксономий в WordPress

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

• add_term_meta - добавляет данные
• get_term_meta - возвращает данные из поля
• has_term_meta - возвращает все сохранённые данные для элемента
• update_term_meta - обновляет данные в поле
• delete_term_meta - удаляет поле

Далее эти функции будут рассмотрены по порядку.

Добавить данные в поле - add_term_meta

Функция добавления данных произволььного поля "add_term_meta":

add_term_meta( $term_id, $key, $value, $unique );

Рассмотрим аргументы функции:

Название	Тип данных	Описание
$term_id	число	ID термина таксономии.
$key	строка	Название произвольного поля (латиницей).
$value	строка	Значение поля
$unique	логический	Ключ должен быть уникальным. По умолчанию: "false" - можно создать несколько полей с одинаковым ключом

Функция возвращает "ID" добавленного поля в случае успешного добавления поля, "WP_Error" в случае неверно заданного ID таксономии "term_id" и "false", если поле не удалось добавить.

Примеры использования:

<?php
add_term_meta(
   7, // id термина таксономии
   'food', // название поля
   'cheese', // значение поля
   true // название поля должно быть уникальным
);

Получение данных из поля - get_term_meta

Для получения значения поля можно использовать функцию "get_term_meta". Если в поле содержится сериализованный массив (PHP функцией "serialize"), то он будет обработан функцией для распаковки данных - "unserialize". Функция возвращает либо объект, строку (даже если записывалось число), либо массив:

$val = get_term_meta( $term_id, $key, $single );

Название	Тип данных	Описание
$term_id	число	ID термина таксономии.
$key	строка	Название произвольного поля (латиницей).
$single	логический	В положении "false" (по умолчанию) вернёт массив из всех значений полей (используйте, если полей с таким ключом несколько). В положении "true" вернёт только одно первое полученное значение из поля, даже если полей с таким ключом несколько.

Примеры использования:

<?php
$food = get_term_meta(
   7, // id термина таксономии
   'food', // название поля
   true
);
echo $food; // распечатает "cheese"

Получение данных из поля - has_term_meta

Для получения всех значений полей можно использовать функцию "has_term_meta". Функция возвращает либо массив из всех метаданных объекта, либо "false" в случае неудачи:

$val = has_term_meta( $term_id, $key, $single );

Название	Тип данных	Описание
$term_id	число	ID термина таксономии.

Примеры использования:

<?php
$food = has_term_meta(
   7 // id термина таксономии
);
print_r($food); // распечатает массив "array( 0 => "cheese" )

Обновление значения поля - update_term_meta

Для изменения значения поля используется функция "update_term_meta". Перед внесением изменений эта функция проверяет поле на существование и добавляет его. Фактически её можно использовать вместо функции добавления данных "add_term_meta".

Функция возвращает "false" в случае неудачи, "true" в случае успешного обновления поля, "WP_Error" в случае неудачи и ID нового поля, если оно было создано.

Как и в случае с "add_term_meta" функция "update_term_meta" проверяет является ли запись ревизией. И в случае таковой функция автоматически находит родительскую запись и изменяет значение поля именно у неё.

Рассмотрим аргументы этой функции:

update_term_meta( $term_id, $key, $value, $prev_value );

Название	Тип данных	Описание
$term_id	число	ID термина таксономии.
$key	строка	Название произвольного поля (латиницей).
$value	строка/массив	Значение поля. Если передать массив, то он будет сериализован PHP функцией "serialize".
$prev_value	строка/массив	Текущее значение поля, которое собираемся изменить. Нужно на случай, если есть несколько произвольных полей с одинаковым названием, чтобы изменить именно одно. Иначе будут изменены все значения полей с одинаковым названием.

Примеры использования:

<?php
update_term_meta(
   7, // id термина таксономии
   'food', // название поля
   'milk' // новое значение поля
);

Удаление поля - delete_term_meta

Для удаления поля используйте функцию "delete_term_meta". При успешном удалении вернётся "true", иначе "false":

delete_term_meta( $term_id, $key, $value );

Рассмотрим аргументы этой функции:

Название	Тип данных	Описание
$term_id	число	ID термина таксономии.
$key	строка	Название произвольного поля (латиницей), которое необходимо удалить.
$value	строка	Значение поля, которое нужно удалить. Используйте это на тот случай, если есть несколько произвольных полей с одинаковым названием, чтобы удалить именно одно. Иначе будут удалены все поля с одинаковым названием.

Примеры использования:

<?php
delete_term_meta(
   7, // id термина таксономии
   'food' // название поля
);