register_rest_field()
Реєструє нове поле REST для зазначеного типу REST об’єкта (ресурсу).
Функцію потрібно викликати на події rest_api_init . Використання цієї події замість init запобігає реєстрації поля під час запитів до WordPress, які не використовують rest API.
Як працює функція
У REST API використовується глобальна змінна $wp_rest_additional_fields . Вона містить у собі всі поля відповіді, які виводяться для окремого об’єкта (ресурсу). REST API використовує функцію register_rest_field() як допоміжну, щоб додати поле в цю глобальну змінну. Робота з цією глобальною змінною безпосередньо не рекомендується з причин зворотної сумісності.
Для кожного ресурсу REST (пости, терміни, коментарі, користувачі і т.д.) змінна $wp_rest_additional_fields містить масив з назвами полів і колббек функціями для отримання або оновлення значень цих полів.
wp_parse_args()
(швидкість світла) | 50000 разів – 0.04 сек
(швидкість світла) |
PHP 7.1.11, WP 4.9.8
Хуків немає.
Повертає
null. Нічого (null)
Використання
register_rest_field( $object_type, $attribute, $args );
-
$object_type
(рядок/масив) (обов’язковий) Назва ресурсу REST для якого реєструється поле. Декілька ресурсів можна вказати в масиві.
Тут необхідно вказати те що в результаті виходить у полі
titleз масиву, який поверне спосіб контролераget_item_schema()поточного REST ресурсу. Наприклад, для користувачів потрібно вказатиuser– дивимося, що знаходиться в title у коді методу WP_REST_Users_Controller::get_item_schema() .Можливі значення:
- Терміни:
ярлык таксономии. Наприкладcategory,custom_taxonomy. Для міток виняток: потрібно вказатиtag, а не post_tag – см WP_REST_Terms_Controller::get_item_schema() . - Пости:
ярлык типа поста. Наприклад:post,page,custom_post_type. - Користувачі:
user. - Коментарі:
comment.
- Терміни:
-
$attribute
(рядок) (обов’язковий) - Назва поля. Це поле буде використано як ключ в об’єкті відповіді REST.
-
$args
(масив) Параметри обробки вказаного поля під час запиту REST.
$get_callback (рядок/масив/null)
PHP Функція для отримання значення поля.
Типово: null – значення не буде показано у відповіді$update_callback (рядок/масив/null)
PHP Функція, яка використовується для встановлення та оновлення значення поля.
Типово: null – значення не може бути встановлене або оновлено- $schema (рядок/масив/null)
Масив описує схему цього поля.
Типово: null – схема не буде показана
За замовчуванням: array()
Приклади
#1 Створюємо поле, що виводить ім’я автора поста
add_action( 'rest_api_init', function(){
register_rest_field( 'post', 'my_awesome_field', array(
'get_callback' => function( $post, $field_name, $request ){
return get_the_author_meta( 'display_name', $post['author'] );
},
'update_callback' => null,
'schema' => [
'description' => __( 'User public name', 'my_domain' ),
'type' => 'string'
],
)));
} );Тепер поле my_awesome_field – можна знайти у json відповіді маршруту http://example.com/wp-json/wp/v2/posts .
#2 Отримуємо кастомні пости за довільним полем. Або оновлюємо довільне поле кастомного посту
add_action( 'rest_api_init', 'slug_register_my_post_types');
function slug_register_my_post_types() {
register_rest_field( 'my_post_type', 'my_custom_field',
array(
'get_callback' => function ( $object, $field_name, $request ) {
return get_post_meta( $object['id'], $field_name );
},
'update_callback' => function ( $value, $object, $field_name ) {
if ( ! $value || ! is_string( $value ) ) {
return;
}
return update_post_meta( $object->ID, $field_name, strip_tags( $value ) );
},
'schema' => null,
)
);
}Таким GET запитом можна отримати список постів, відсортованих за значенням метаполя my_custom_field :
https://myexample.com/wp-json/wp/v2/my_post_type?filter[meta_query][0][key]=my_custom_field&filter[meta_query][0][value]=my_find_value
А оновити значення цього мета поля можна запитом POST
https://myexample.com/wp-json/wp/v2/my_post_type/{id}
де {id} це id потрібного посту і параметрах запиту зазначено: my_custom_field => 'new_value'.
нотатки
- Global. Масив. $wp_rest_additional_fields Holds registered fields, організований за об’єктом типу.
список змін
| З версії 4.7.0 | Введено. |
Код register_rest_field() register rest field WP 6.0.2
function register_rest_field( $object_type, $attribute, $args = array() ) {
global $wp_rest_additional_fields;
$defaults = array(
'get_callback' => null,
'update_callback' => null,
'schema' => null,
);
$ args = wp_parse_args ($ args, $ defaults);
$object_types = (array) $object_type;
foreach ( $object_types as $object_type ) {
$wp_rest_additional_fields[ $object_type ][ $attribute ] = $args;
}
}