register_rest_route() в WordPress: Полное руководство

Функция register_rest_route() используется для регистрации маршрутов и их конечных точек в REST API WordPress. Это позволяет разработчикам создавать пользовательские маршруты и отвечать на них с помощью PHP-функций.

Основы использования register_rest_route()

register_rest_route( $namespace, $route, $args, $override );

• $namespace (строка): Первая часть маршрута, следующая за префиксом /wp-json/. Обычно это название вашего плагина или темы, например, myplugin/v1.
• $route (строка): Вторая часть маршрута. Поддерживает регулярные выражения, например, /author/(?P<id>\d+).
• $args (массив): Параметры для конечной точки.
  • methods (строка|массив) — HTTP методы (GET, POST, PUT, DELETE и т.д.).
  • callback (callable) — Функция, которая будет вызвана при обращении к маршруту.
  • permission_callback (callable) — Функция для проверки разрешений.
• $override (логический): Определяет, нужно ли переопределять существующий маршрут. По умолчанию false.

Пример 1: Создание пользовательского маршрута для получения данных

Этот пример демонстрирует, как зарегистрировать новый маршрут и добавить коллбэк-функцию для обработки запроса.

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/custom-data', array(
        'methods'  => 'GET',
        'callback' => 'get_custom_data',
    ) );
} );

function get_custom_data( $data ) {
    $response = array(
        'message' => 'Hello, this is custom data!',
        'data'    => $data,
    );
    return rest_ensure_response( $response );
}

В этом примере мы регистрируем маршрут /wp-json/myplugin/v1/custom-data, который возвращает простое сообщение и переданные данные.

Пример 2: Добавление маршрута с проверкой разрешений

Этот пример показывает, как добавить проверку разрешений для маршрута.

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/secure-data', array(
        'methods'             => 'GET',
        'callback'            => 'get_secure_data',
        'permission_callback' => 'check_user_permissions',
    ) );
} );

function get_secure_data( $data ) {
    $response = array(
        'message' => 'You have access to secure data!',
        'data'    => $data,
    );
    return rest_ensure_response( $response );
}

function check_user_permissions( $request ) {
    return current_user_can( 'edit_others_posts' );
}

В этом примере маршрут /wp-json/myplugin/v1/secure-data доступен только пользователям с правами на редактирование чужих постов.

Подробное объяснение

• Регистрация маршрута: Функция register_rest_route() регистрирует новый маршрут, который доступен по заданному пути и namespace.
• Коллбэк-функция: Аргумент callback указывает функцию, которая будет выполнена при обращении к маршруту. Эта функция должна возвращать ответ в формате, поддерживаемом REST API.
• Проверка разрешений: Аргумент permission_callback указывает функцию, которая проверяет, имеет ли текущий пользователь необходимые права для доступа к маршруту. Если функция возвращает false, доступ к маршруту будет запрещен.

Аргументы функции

methods

Определяет методы HTTP, которые будут поддерживаться конечной точкой. Можно указать строку или массив методов.

'methods' => 'GET' // Или массив ['GET', 'POST']

Также можно использовать константы класса WP_REST_Server:

• WP_REST_Server::READABLE (GET)
• WP_REST_Server::CREATABLE (POST)
• WP_REST_Server::EDITABLE (POST, PUT, PATCH)
• WP_REST_Server::DELETABLE (DELETE)
• WP_REST_Server::ALLMETHODS (GET, POST, PUT, PATCH, DELETE)

callback

Функция, которая будет вызвана при обращении к маршруту. Функция должна возвращать ответ в формате JSON.

'callback' => 'my_callback_function'

Пример функции:

function my_callback_function( WP_REST_Request $request ) {
    return array( 'message' => 'Hello, World!' );
}

permission_callback

Функция, проверяющая права доступа пользователя. Обязательна с версии WordPress 5.5.

'permission_callback' => 'my_permission_callback'

Пример функции:

function my_permission_callback() {
    return current_user_can( 'edit_others_posts' );
}

args

Массив аргументов, которые могут быть переданы в маршрут. Ключи массива — это имена аргументов, значения — массивы с их настройками.

'args' => array(
    'param_name' => array(
        'default' => null,
        'required' => true,
        'validate_callback' => 'my_validate_callback',
        'sanitize_callback' => 'my_sanitize_callback'
    ),
)

Пример функции для проверки аргументов:

function my_validate_callback( $param, $request, $key ) {
    return is_numeric( $param );
}

function my_sanitize_callback( $param, $request, $key ) {
    return (int) $param;
}

Дополнительные параметры

• show_in_index (true/false): Определяет, нужно ли показывать маршрут в индексе всех маршрутов.
• description (строка): Описание маршрута.
• type (строка): Тип значения параметра (array, object, string, number, integer, boolean, null).
• minimum / maximum (число): Минимальное или максимальное значение для параметра.
• format (строка): Дополнительный формат строки (date-time, uri, email, ip, uuid, hex-color).
• enum (массив): Список допустимых значений для параметра.

Заключение

Функция register_rest_route() предоставляет мощный способ расширения REST API WordPress. Она позволяет создавать собственные маршруты с кастомной логикой и проверками, что делает возможным интеграцию с внешними системами и приложениями.