Как добавить загрузку файлов через REST API WordPress

REST API в WordPress — мощный инструмент для взаимодействия с сайтом из внешних приложений и сервисов. Но по умолчанию загрузка файлов через REST API не реализована напрямую. В этой статье разберём, как добавить поддержку загрузки файлов через REST API WordPress с примерами кода, чтобы можно было отправлять изображения, документы и другие файлы в медиабиблиотеку сайта.

Почему загрузка файлов через REST API важна

Многие современные приложения и мобильные клиенты используют REST API для обмена данными с сайтом. Возможность отправлять файлы напрямую через API упрощает интеграцию, автоматизирует публикацию контента и расширяет функционал сайта.

Без поддержки загрузки файлов приходится использовать обходные пути — например, сначала загружать файлы на свой сервер, а потом передавать URL для импорта. Это неудобно и не безопасно.

Реализовав загрузку файлов через REST API, мы получаем более гибкий и современный способ управления медиа.

Добавление маршрута загрузки файлов через REST API в WordPress

Для начала создадим свой endpoint REST API, который будет принимать файл из POST-запроса и сохранять его в медиабиблиотеку WordPress.

Добавим следующий код в файл functions.php вашей темы или в отдельный плагин:

add_action('rest_api_init', function () {
    register_rest_route('wpcodes/v1', '/upload', [
        'methods' => 'POST',
        'callback' => 'wpcodes_handle_file_upload',
        'permission_callback' => function () {
            return current_user_can('upload_files');
        },
    ]);
});

function wpcodes_handle_file_upload(WP_REST_Request $request) {
    $files = $request->get_file_params();

    if (empty($files['file'])) {
        return new WP_REST_Response(['error' => 'Файл не найден в запросе'], 400);
    }

    $file = $files['file'];

    require_once(ABSPATH . 'wp-admin/includes/file.php');
    require_once(ABSPATH . 'wp-admin/includes/media.php');
    require_once(ABSPATH . 'wp-admin/includes/image.php');

    $upload = wp_handle_upload($file, ['test_form' => false]);

    if (isset($upload['error'])) {
        return new WP_REST_Response(['error' => $upload['error']], 500);
    }

    $attachment = [
        'post_mime_type' => $upload['type'],
        'post_title' => sanitize_file_name($file['name']),
        'post_content' => '',
        'post_status' => 'inherit'
    ];

    $attach_id = wp_insert_attachment($attachment, $upload['file']);

    $attach_data = wp_generate_attachment_metadata($attach_id, $upload['file']);
    wp_update_attachment_metadata($attach_id, $attach_data);

    return new WP_REST_Response(['attachment_id' => $attach_id, 'url' => wp_get_attachment_url($attach_id)], 201);
}

Объяснение кода:

• Регистрируем REST маршрут /wp-json/wpcodes/v1/upload с методом POST.
• В коллбэке проверяем наличие файла в параметрах запроса.
• Используем стандартные функции WordPress для обработки загрузки wp_handle_upload и создания вложения wp_insert_attachment.
• Возвращаем ID вложения и URL загруженного файла в ответе.
• Проверяем права пользователя с помощью current_user_can('upload_files'), чтобы обезопасить загрузку.

Как отправить файл через REST API клиентом

Для тестирования можно использовать curl или написать код на PHP, JavaScript и других языках. Пример запроса через curl:

curl -X POST https://example.com/wp-json/wpcodes/v1/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F file=@/path/to/file.jpg

Обратите внимание, что для авторизации нужно использовать валидный токен (например, JWT или cookie авторизацию). Без авторизации сервер вернёт ошибку 401.

Пример запроса на PHP с использованием wp_remote_post

$file_path = '/path/to/file.jpg';
$file_contents = file_get_contents($file_path);

$response = wp_remote_post('https://example.com/wp-json/wpcodes/v1/upload', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_JWT_TOKEN',
    ],
    'body' => [
        'file' => curl_file_create($file_path),
    ],
]);

if (is_wp_error($response)) {
    echo 'Ошибка запроса: ' . $response->get_error_message();
} else {
    $data = json_decode(wp_remote_retrieve_body($response), true);
    print_r($data);
}

Обработка ошибок и безопасность при загрузке файлов через REST API

При работе с загрузкой файлов важно учитывать несколько моментов:

• Авторизация: Всегда проверяйте права пользователя. В нашем примере используется current_user_can('upload_files'). Можно добавить дополнительную проверку токенов или ролей.
• Типы файлов: Можно ограничить допустимые форматы, проверяя $file['type'] или расширение файла, чтобы не загружать опасные файлы.
• Размер файлов: Следите за ограничениями PHP и сервера, а также добавьте проверки в коде, чтобы не принимать слишком большие файлы.
• Обработка ошибок: Всегда возвращайте понятные сообщения об ошибках, чтобы клиент понимал, что пошло не так.

Пример добавления проверки формата файла:

function wpcodes_handle_file_upload(WP_REST_Request $request) {
    $files = $request->get_file_params();
    if (empty($files['file'])) {
        return new WP_REST_Response(['error' => 'Файл не найден в запросе'], 400);
    }
    $file = $files['file'];

    $allowed_types = ['image/jpeg', 'image/png', 'application/pdf'];
    if (!in_array($file['type'], $allowed_types)) {
        return new WP_REST_Response(['error' => 'Недопустимый тип файла'], 415);
    }
    // Далее загрузка как ранее
}

Использование плагинов для расширения возможностей REST API загрузки

Если не хочется писать код с нуля, можно использовать готовые плагины, которые добавляют загрузку файлов через REST API:

• WP REST API Media — расширяет стандартный API, добавляет поддержку загрузки и управления медиа.
• Clearfy Pro — плагин для оптимизации и безопасности, содержит настройки для REST API и медиа.

Эти решения экономят время и упрощают интеграцию, но иногда нужна кастомизация, которую проще сделать самому через код.

Итоги и полезные советы

Добавление загрузки файлов через REST API — полезный навык для разработчиков WordPress. Это позволяет создавать гибкие приложения и расширять функционал сайта.

Основные шаги:

• Создать собственный REST маршрут с проверкой прав доступа.
• Обработать входящий файл через стандартные функции WordPress.
• Вернуть клиенту информацию о загруженном файле.
• Обязательно реализовать проверки безопасности.

Таким способом можно легко интегрировать загрузку файлов из мобильных приложений, внешних сервисов и других систем.