add_metadata

Добавляет мета (дополнительные) данные к любому объекту (запись, комментарий, пользователь).

Эта функция является своего рода API для управления метаданными. Так как, для нее можно создать произвольную таблицу в БД и записывать/удалять данные от туда (см. ниже).

Родственные функции:

update_metadata($meta_type, $object_id, $meta_key, $meta_value, [$prev_value])

— можно использовать вместо add_metadata(), так как она сначала проверяет существование ключа;

delete_metadata($meta_type, $object_id, $meta_key, [$meta_value], [$delete_all])

— удаляет данные по ключу;

get_metadata($meta_type, $object_id, [$meta_key], [$single])

— получает данные из БД, по ключу.

Хуки из функции:
added_(meta_type)_meta
add_(meta_type)_meta
add_(meta_type)_metadata
Возвращает

false / true, в зависимости от того удалось ли добавить метаданные.

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

add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique );
$meta_type(строка) (обязательный)
Тип объекта, мета данные для которого нужно добавить. Может быть: comment, post или user (всегда в единственном числе).
По умолчанию: нет
$object_id(число) (обязательный)
ID объекта, мета данные для которого добавляются.
По умолчанию: нет
$meta_key(строка) (обязательный)
Ключ – название типа дополнительных данных.
По умолчанию: нет
$meta_value(строка) (обязательный)
Значение ключа дополнительных данных.
По умолчанию: нет
$unique(логический)

Определение уникальности ключа.

  • false – означает, что для этого объекта может быть определено несколько одинаковых ключей.
  • true – значит, что ключ для этого объекта может быть только один, т.е. если такой ключ уже существует, то функция не добавит никаких данных.
    По умолчанию: false

Таблицы метаданных в Базе Данных WP

add_metadata() подразумевает существование нужных таблиц в БД, таблиц куда метаданные будут записываться. По умолчанию в WordPress существует 4 такие таблицы для разных объектов (записи, комментарии, пользователи, элементы таксономии):

wp_commentmeta
Метаданные для каждого комментария.
wp_postmeta
Метаданные для постов. Сюда записываются привычные в WordPress “произвольные поля поста”
wp_usermeta
Дополнительные данные о пользователе.
wp_termmeta
Дополнительные данные для элементов таксономии. С версии WP 4.4.

Создание произвольных таблиц в БД

Если нужно записывать какие-либо другие данные (для других объектов), то можно создать свою таблицу и пользоваться add_metadata() и производными ей функциями (update_metadata(), delete_metadata(), get_metadata()), для созданной таблицы.

Структура создаваемой таблицы:

meta_id
bigint(20) UNSIGNED NOT NULL auto_increment
object_id
Название поля будет [название_объекта]_id. bigint(20) UNSIGNED NOT NULL
meta_key
varchar(255)
meta_value
longtext

Примеры

1. Пример создания дополнительных данных для комментария 45:

<?php  add_metadata('comment', 45, 'vocation', 'Строитель', true) ?>

2. Создание произвольной таблицы метаданных.

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

Пример создания таблицы метаданных: term:

global $wpdb;
   $result = false;
   //Создаем таблицу в БД, если её не существует
   $sql = sprintf('CREATE TABLE IF NOT EXISTS `%stermmeta` (
	  `meta_id` bigint(20) UNSIGNED NOT NULL auto_increment,
	  `term_id` bigint(20) UNSIGNED NOT NULL,
	  `meta_key` varchar(255),
	  `meta_value` longtext,
	  PRIMARY KEY (`meta_id`)
   )', $wpdb->prefix);
   $result = $wpdb->query($sql);

Заметка! После того как таблица создана, её нужно зарегистрировать в объекте $wpdb, для того чтобы потом проще было с ней работать через класс $wpdb.

Для регистрации определите свойство класса $wpdb->termmeta в котором укажите название таблицы (делать это нужно через хук init или перед использованием произвольных функций):

global $wpdb;
   $wpdb->termmeta = $wpdb->prefix.'termmeta';

Добавление данных в таблицу Term

Теперь, когда таблица создана, добавить данные туда можно так:

add_metadata('term', $_GET['tag_ID'], 'gender', 'M' ,true);
   add_metadata('term', $_GET['tag_ID'], 'age', '29', true);
   add_metadata('term', $_GET['tag_ID'], 'favourite_colour', 'Green', true);

Также, для создания метаданных у терминов, можете использовать плагин taxonomy metadata (я его подробно описал).

Код из


wp-includes/meta.php

WP 4.7.2

<?php
function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
	global $wpdb;

	if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
		return false;
	}

	$object_id = absint( $object_id );
	if ( ! $object_id ) {
		return false;
	}

	$table = _get_meta_table( $meta_type );
	if ( ! $table ) {
		return false;
	}

	$column = sanitize_key($meta_type . '_id');

	// expected_slashed ($meta_key)
	$meta_key = wp_unslash($meta_key);
	$meta_value = wp_unslash($meta_value);
	$meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );

	/**
	 * Filters whether to add metadata of a specific type.
	 *
	 * The dynamic portion of the hook, `$meta_type`, refers to the meta
	 * object type (comment, post, or user). Returning a non-null value
	 * will effectively short-circuit the function.
	 *
	 * @since 3.1.0
	 *
	 * @param null|bool $check      Whether to allow adding metadata for the given type.
	 * @param int       $object_id  Object ID.
	 * @param string    $meta_key   Meta key.
	 * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
	 * @param bool      $unique     Whether the specified meta key should be unique
	 *                              for the object. Optional. Default false.
	 */
	$check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
	if ( null !== $check )
		return $check;

	if ( $unique && $wpdb->get_var( $wpdb->prepare(
		"SELECT COUNT(*) FROM $table WHERE meta_key = %s AND $column = %d",
		$meta_key, $object_id ) ) )
		return false;

	$_meta_value = $meta_value;
	$meta_value = maybe_serialize( $meta_value );

	/**
	 * Fires immediately before meta of a specific type is added.
	 *
	 * The dynamic portion of the hook, `$meta_type`, refers to the meta
	 * object type (comment, post, or user).
	 *
	 * @since 3.1.0
	 *
	 * @param int    $object_id  Object ID.
	 * @param string $meta_key   Meta key.
	 * @param mixed  $meta_value Meta value.
	 */
	do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );

	$result = $wpdb->insert( $table, array(
		$column => $object_id,
		'meta_key' => $meta_key,
		'meta_value' => $meta_value
	) );

	if ( ! $result )
		return false;

	$mid = (int) $wpdb->insert_id;

	wp_cache_delete($object_id, $meta_type . '_meta');

	/**
	 * Fires immediately after meta of a specific type is added.
	 *
	 * The dynamic portion of the hook, `$meta_type`, refers to the meta
	 * object type (comment, post, or user).
	 *
	 * @since 2.9.0
	 *
	 * @param int    $mid        The meta ID after successful update.
	 * @param int    $object_id  Object ID.
	 * @param string $meta_key   Meta key.
	 * @param mixed  $meta_value Meta value.
	 */
	do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );

	return $mid;
}