register_meta() WP 3.3.0

Реєструє метаполе (ключ довільного поля).

Реєстрація метаполя потрібна для використання його в різних API, наприклад для REST API. Або таку регу можна використовувати при додаванні полів до метабоксу: add_meta_box()

Рекомендується реєструвати мета-ключі для конкретної комбінації типу об’єкта та підтипу об’єкта. Якщо підтип об’єкта не вказано, мета-ключ буде зареєстровано для всього типу об’єкта, однак він може бути частково перевизначений у випадку, якщо для того ж типу об’єкта і підтипу існує інший, аналогічний мета-ключ.

Якщо тип об’єкта не підтримує жодних підтипів, наприклад, користувачі або коментарі, цю функцію слід викликати без зазначення підтипу.

Поведінка цієї функції є чимось походом на register_post_type() – дані аналогічно зберігаються в глобальну змінну $wp_meta_keys. Це дозволить отримувати дані метаполя в будь-якому місці двигуна, роблячи зручним розширення коду.

Реєстрація у глобальну змінну доступна лише з WP 4.6. Очевидно, що функція і технологія яку вона має на увазі почне повсюдно використовуватися з версії WordPress 4.6.

  • Використовуйте get_registered_meta_keys() , щоб отримати дані всіх зареєстрованих метаполів.

  • Використовуйте unregister_meta_key() , щоб видалити раніше зареєстроване метаполе.

Хуки з функції

Повертає

true|false.

  • true – якщо мета-ключ був успішно зареєстрований у глобальному масиві $wp_meta_keys.
  • false – якщо не вдалося зареєструвати ключ.

Використання

register_meta( $object_type, $meta_key, $args, $deprecated );
$object_type
(рядок) (обов’язковий)
Тип об’єкта якого реєструється метаполі:
post,
user,
comment,
term. Параметр
$meta_type з функцій
{add/get/update/delete}_metadata( $meta_type, …)
$meta_key
(рядок) (обов’язковий)
Назва ключа, що реєструється.
$args
(масив) (обов’язковий)

Дані описують метаполі. За замовчуванням такі:

$ args = array (
	'object_subtype' => '',
	'type' => 'string',
	'description' => '',
	'default' => '', // WP 5.5
	'single' => false,
	'sanitize_callback' => null,
	'auth_callback' => null,
	'show_in_rest' => false,
);
  • object_subtype (рядок) (з версії 4.9.8)
    Точний тип об’єкта для якого реєструється метаполе. Наприклад, якщо $object_type = post , тут можна вказати назву типу записи якого реєструється метаполі. Якщо залишити цей параметр порожнім, метаполе буде зареєстровано для всіх $object_type .
    За замовчуванням: ”

  • Тип (рядок)
    Тип даних значення метаполя . Назва типу потрібно вказувати без скорочення:

    • string
    • boolean
    • integer
    • number
    • array(WP 5.3)
    • object(WP 5.3)

    За замовчуванням: ‘string’

  • description (рядок)
    Опис даних розміщених у метаполі. Щоб можна було прочитати і зрозуміти, що тут зберігається…
    За замовчуванням: ”

  • single (логічний)
    true – може бути лише одне метаполе з такою назвою.
    false – таких метаполів може бути декілька.
    Типово: false

  • default (рядок) (WP 5.5)
    Значення за промовчанням повертається функцією get_metadata() , якщо воно ще не встановлено. При використанні жодного мета-ключа значення за замовчуванням використовується для першого запису. Іншими словами, при виклику get_metadata() з $single=false , задане значення буде обернено в масив.
    За замовчуванням: ”

  • sanitize_callback (рядок)
    Назва функції або методу, який буде використаний для очищення значення метаполя при збереженні. Вказана функція буде додано до фільтра: sanitize_{$object_type}_meta_{$meta_key}.

    Функція отримає три параметри: $meta_value, $meta_key, $object_type. Докладніше див. код функції sanitize_meta() .

    Типово: null

  • auth_callback (рядок)
    Функція або метод, яка буде викликана для перевірки прав edit_post_meta, add_post_metaі delete_post_meta. Вказана функція буде додана до фільтра: auth_(object_type)_meta_(meta_key) .

    Функція повинна повернути true або false, що означатиме дозволяти або забороняти відповідну дію користувачеві. Якщо не вказати функцію, то права на створення/видалення метаполя отримають всі користувачі, які мають права редагувати метаполя.

    Функція отримає шість параметрів:

    function my_callback( $false, $meta_key, $post_id, $user_id, $cap, $caps ){
    	// ваша перевірка
    }

    Докладніше дивіться код функції map_meta_cap() .

    Дивіться фільтри:

    Типово: null (__return_true)

  • show_in_rest (логічний)
    Чи потрібно показувати ці дані у запитах REST . Чи є дані цього метаполя публічними.
    Типово: false
$deprecated
(рядок/масив)
Застарілий параметр версії 4.6. Використовуйте $args натомість.


Типово: null

Приклади

0

#1 Демонстрація роботи

Для початку давайте регне метаполі і подивимося що додалося в глобальний масив:

register_meta( 'post', 'bookname', array(
	'type' => 'string',
	'description' => 'Назва книги',
	'single' => true,
	'sanitize_callback' => null,
	'auth_callback' => null,
	'show_in_rest' => false,
)));

global $wp_meta_keys;

print_r($wp_meta_keys);

/*
Array
(
	[post] => Array
		(
			[bookname] => Array
				(
					[type] => string
					[description] => Назва книги
					[single] => 1
					[sanitize_callback] =>
					[auth_callback] => __return_true
					[show_in_rest] =>
				)

		)
)
*/
0

#2 Реєстрація метаполя

Тепер давайте зареєструємо метаполі з функціями доступу та очищення та перевіримо як це працює:

register_meta( 'post', 'bookname', array(
	'type' => 'string',
	'description' => 'Назва книги',
	'single' => true,
	'sanitize_callback' => 'sanitize_bookname_meta',
	'auth_callback' => 'auth_bookname_meta',
	'show_in_rest' => false,
)));

function sanitize_bookname_meta( $meta_value, $meta_key, $object_type ){
	$meta_value = wp_strip_all_tags( $meta_value ); // Видалимо html теги

	return $meta_value;
}

function auth_bookname_meta( $false, $meta_key, $postID, $user_id, $cap, $caps ){
	// Заборонимо створення та редагування цього метаполя для всіх, крім адміну
	if( ! current_user_can('manage_options') )
		return false;
	return true;
}

В результаті, якщо зайти на сторінку редагування запису і спробувати створити метаполі bookname:

  • Якщо ви увійшли як адмін – метаполе створиться.
  • Якщо редактор, автор тощо. – Ви не зможете створити це метаполе.

За це відповідає параметрauth_callback

Далі, якщо в значенні вказати рядок з HTML-тегами, при оновленні вони будуть вирізані.
За це відповідає параметрsanitize_callback

Параметри: type, description, singleу версії WP 4.6, носять лише інформаційний характер і поки що ніде не використовуються…

0

#3 Реєстрація метаполя для конкретного типу запису

З WordPress 4.9.8 ця функція підтримує реєстрацію метаданих не тільки всього типу об’єкта (записи, терміни, коментарі, користувачі), але й конкретного підтипу (наприклад, певного типу записи чи таксономії). Для цього вказуємо параметр object_subtype:

register_meta( 'post', 'my_meta_key', array(
	'object_subtype' => 'my_post_type',
	'show_in_rest' => true,
	'sanitize_callback' => 'absint',
)));

Тепер зазначене метаполе вважатиметься метаполем типу запису my_post_typeта іншого типу.

Так само можна регнути метаполі для типу запису, за допомогою функції register_post_meta() :

register_post_meta( 'my_post_type', 'my_meta_key', array(
	'show_in_rest' => true,
	'sanitize_callback' => 'absint',
)));

register_post_meta() – це функція обгортка і створена для більш зрозумілої та зручної реєстрації метаполя.

список змін

З версії 3.3.0Введено.
З версії 4.6.0Modified для підтримки array of data для підключення до registered meta keys . Подібні argumenty для $sanitize_callback і $auth_callback повинні бути сформовані в цю array.
З версії 4.9.8$object_subtype argument був приєднаний до arguments array.
З версії 5.3.0Значні типи meta expanded включають “array” і “object”.
З версії 5.5.0$default argument був added до arguments array.

Код register_meta() WP 6.0.2

function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
	global $wp_meta_keys;

	if ( ! is_array( $wp_meta_keys ) ) {
		$wp_meta_keys = array();
	}

	$defaults = array(
		'object_subtype' => '',
		'type' => 'string',
		'description' => '',
		'default' => '',
		'single' => false,
		'sanitize_callback' => null,
		'auth_callback' => null,
		'show_in_rest' => false,
	);

	// Вони використовуються для окремих арг для санітарного та авт callbacks.
	$has_old_sanitize_cb = false;
	$has_old_auth_cb = false;

	if ( is_callable( $args ) ) {
		$ args = array (
			'sanitize_callback' => $args,
		);

		$has_old_sanitize_cb = true;
	} else {
		$args = (array) $args;
	}

	if ( is_callable( $deprecated ) ) {
		$args['auth_callback'] = $deprecated;
		$has_old_auth_cb = true;
	}

	/**
	 * Filters the registration arguments при registering meta.
	 *
	 * @ Since 4.6.0
	 *
	 * @param array $args Array of meta registration arguments.
	 * @param array $defaults Array of default arguments.
	 * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
	 * або будь-який інший object type with an associated meta table.
	 * @param string $meta_key Meta key.
	 */
	$args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key );
	unset( $defaults['default'] );
	$ args = wp_parse_args ($ args, $ defaults);

	// Require an item schema when registering array meta.
	if ( false !== $args['show_in_rest'] && 'array' === $args['type'] ) {
		if ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) {
			_doing_it_wrong( __FUNCTION__, __( 'When registering "array" meta type to show in the REST API, ви повинні визначати schema for each array item in "show_in_rest.schema.items".' ), '5.3.

			return false;
		}
	}

	$object_subtype =! empty( $args['object_subtype'] ) ? $args['object_subtype'] : '';

	// If `auth_callback` is not provided, fall back to `is_protected_meta()`.
	if ( empty( $args['auth_callback'] ) ) {
		if ( is_protected_meta( $meta_key, $object_type ) ) {
			$args['auth_callback'] = '__return_false';
		} else {
			$args['auth_callback'] = '__return_true';
		}
	}

	// Back-compat: old sanitize і auth callbacks є applied to all of an object type.
	if ( is_callable( $args['sanitize_callback'] ) ) {
		if ( ! empty( $object_subtype ) ) {
			add_filter( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['sanitize_callback'], 10, 4);
		} else {
			add_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'], 10, 3);
		}
	}

	if ( is_callable( $args['auth_callback'] ) ) {
		if ( ! empty( $object_subtype ) ) {
			add_filter( "auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['auth_callback'], 10, 6);
		} else {
			add_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'], 10, 6);
		}
	}

	if ( array_key_exists( 'default', $args ) ) {
		$schema = $args;
		if ( is_array( $args['show_in_rest'] ) && isset( $args['show_in_rest']['schema'] ) ) {
			$schema = array_merge( $schema, $args['show_in_rest']['schema'] );
		}

		$check = rest_validate_value_from_schema( $args['default'], $schema );
		if ( is_wp_error( $check ) ) {
			_doing_it_wrong( __FUNCTION__, __( 'When registering default meta value the data must match the type provided.' ), '5.5.0' );

			return false;
		}

		if ( ! has_filter( "default_{$object_type}_metadata", 'filter_default_metadata' ) ) {
			add_filter( "default_{$object_type}_metadata", 'filter_default_metadata', 10, 5);
		}
	}

	// Global registration тільки contains meta keys registered with array of arguments added in 4.6.0.
	if ( ! $has_old_auth_cb && ! $has_old_sanitize_cb ) {
		unset( $args['object_subtype'] );

		$wp_meta_keys[ $object_type ][ $object_subtype ][ $meta_key ] = $args;

		return true;
	}

	return false;
}

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *