register_meta

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

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

Поведение register_meta() чем-то походе на register_post_type() – данные аналогично сохраняются в глобальную переменную $wp_meta_keys. Это позволит получать данные метаполя в любом месте движка, под разные условия, делая удобным расширение кода.

Регистрация в глобальную переменную доступна только с версии WP 4.6. Подразумевается, что функция и технология которую она подразумевает начнет повсеместно использоваться с версии WordPress 4.6.
Хуки из функции:
register_meta_args
Возвращает

true/false.
true – если мета-ключ был успешно зарегистрирован в глобальном массиве $wp_meta_keys.
false – если не удалось зарегистрировать ключ.

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

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

Данные описывающие метаполе. По умолчанию такие:

$args = array(
	'type'              => 'string',
	'description'       => '',
	'single'            => false,
	'sanitize_callback' => null,
	'auth_callback'     => null,
	'show_in_rest'      => false,
);
  • type (строка)
    Тип данных значения метаполя. Название типа нужно указывать без сокращения: string, array, boolean, integer и т.д.
    По умолчанию: ‘string’

  • description (строка)
    Описание данных размещаемых в метаполе. Чтобы можно было прочитать и понять что тут храниться…
    По умолчанию: ”

  • single (логический)
    true – может быть только одно метаполе с таким названием.
    false – таких метаполей может быть несколько.
    По умолчанию: 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, что будет означать разрешать или запрещать соответствующее действие пользователю. Если не указать функцию, то права на создание/изменения метаполя получат все юзеры обладающие правами редактировать метаполя…

    Функция получит шесть параметров: false, $meta_key, $post->ID, $user_id, $cap, $caps. Подробнее смотрите код функции map_meta_cap() – смотрите фильтры: auth_post_meta_{$meta_key} и auth_post_{$post_type}_meta_{$meta_key}.

    По умолчанию: null (__return_true)

  • show_in_rest (логический)
    Являются ли данные этого метаполя публичными.
    По умолчанию: false
$deprecated(строка/массив)
Устарелый с версии 4.6 параметр. Используйте $args взамен.
По умолчанию: null

Примеры

#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] => 
				)

		)
)
*/

#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, show_in_rest в версии WP 4.6, носят только информационный характер и пока нигде не функционируют…

Код из


wp-includes/meta.php

WP 4.7.2

<?php
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(
		'type'              => 'string',
		'description'       => '',
		'single'            => false,
		'sanitize_callback' => null,
		'auth_callback'     => null,
		'show_in_rest'      => false,
	);

	// There used to be individual args for sanitize and auth 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 when 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 Object type.
	 * @param string $meta_key    Meta key.
	 */
	$args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key );
	$args = wp_parse_args( $args, $defaults );

	// 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 and auth callbacks are applied to all of an object type.
	if ( is_callable( $args['sanitize_callback'] ) ) {
		add_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'], 10, 3 );
	}

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

	// Global registry only contains meta keys registered with the array of arguments added in 4.6.0.
	if ( ! $has_old_auth_cb && ! $has_old_sanitize_cb ) {
		$wp_meta_keys[ $object_type ][ $meta_key ] = $args;

		return true;
	}

	return false;
}

Комментарии:


Оставить комментарий

Your email address will not be published. Required fields are marked *