Как добавить обработку файлов в REST API WordPress с примерами кода

Автор: Наталья Соколова | Опубликовано: 05.02.2026

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

Почему стандартный REST API WordPress не подходит для загрузки файлов

По умолчанию WordPress REST API поддерживает загрузку медиа через эндпоинт /wp/v2/media. Но если вы создаёте собственные кастомные эндпоинты, например, для создания кастомных записей с вложениями, стандартный подход не всегда подходит. Нужно самому реализовать обработку загружаемых файлов, проверить их, сохранить и связать с записью.

Также по умолчанию REST API ожидает JSON, а загрузка файлов требует передачи данных в формате multipart/form-data. Это усложняет задачу, так как нужно корректно обрабатывать такие запросы.

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

Регистрация собственного маршрута REST API с поддержкой загрузки файлов

Для начала зарегистрируем новый маршрут, который будет принимать POST запрос с файлом. Используем хук rest_api_init для регистрации маршрута.

add_action('rest_api_init', function () {
    register_rest_route('wpzoom/v1', '/upload-file', [
        'methods' => 'POST',
        'callback' => 'wpzoom_handle_file_upload',
        'permission_callback' => function () {
            return current_user_can('upload_files');
        },
        'args' => [] // Можно добавить валидацию аргументов
    ]);
});

Здесь мы определяем маршрут /wpzoom/v1/upload-file, который обрабатывается функцией wpzoom_handle_file_upload. Для безопасности разрешаем доступ только пользователям с правом upload_files.

Обработка загрузки файла в колбэке маршрута

Теперь реализуем функцию wpzoom_handle_file_upload, которая будет принимать файл из запроса, проверять его и сохранять в медиабиблиотеку WordPress.

function wpzoom_handle_file_upload(WP_REST_Request $request) {
    // Проверим, что файл передан
    if (empty($_FILES['file'])) {
        return new WP_Error('no_file', 'Не был передан файл', ['status' => 400]);
    }

    $file = $_FILES['file'];

    // Используем встроенную функцию для обработки загрузки
    $overrides = [
        'test_form' => false, // Отключаем проверку формы, так как это REST API
    ];

    $movefile = wp_handle_upload($file, $overrides);

    if ($movefile && !isset($movefile['error'])) {
        // Файл успешно загружен, создадим вложение в медиабиблиотеке
        $filename = $movefile['file'];

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

        $attach_id = wp_insert_attachment($attachment, $filename);

        if (!is_wp_error($attach_id)) {
            require_once(ABSPATH . 'wp-admin/includes/image.php');
            $attach_data = wp_generate_attachment_metadata($attach_id, $filename);
            wp_update_attachment_metadata($attach_id, $attach_data);

            return [
                'success' => true,
                'attachment_id' => $attach_id,
                'url' => wp_get_attachment_url($attach_id),
            ];
        } else {
            return new WP_Error('attachment_error', 'Ошибка при создании вложения', ['status' => 500]);
        }
    } else {
        // Ошибка загрузки
        return new WP_Error('upload_error', $movefile['error'], ['status' => 400]);
    }
}

В этой функции мы используем wp_handle_upload для обработки загрузки и wp_insert_attachment для создания записи вложения. После чего генерируем метаданные вложения с помощью wp_generate_attachment_metadata.

Пример запроса к REST API с загрузкой файла

Чтобы отправить файл на наш эндпоинт, можно использовать curl:

curl -X POST https://your-site.ru/wp-json/wpzoom/v1/upload-file \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F file=@/path/to/file.jpg

Обратите внимание, что для авторизации мы передаём заголовок с токеном, так как маршрут доступен только авторизованным пользователям с правом upload_files.

Как связать загруженный файл с кастомной записью

В реальных задачах часто нужно не просто загрузить файл, а связать его с кастомной записью. Чтобы это сделать, можно расширить обработчик так, чтобы он принимал ID записи и связывал вложение с ней.

function wpzoom_handle_file_upload(WP_REST_Request $request) {
    // Проверка файла как выше
    // ...

    $post_id = $request->get_param('post_id');

    // Загрузка и создание вложения, как в предыдущем коде
    // ...

    if (!is_wp_error($attach_id) && $post_id) {
        // Связываем вложение с записью через метаполе
        update_post_meta($post_id, '_wpzoom_attached_file', $attach_id);
    }

    // Возвращаем результат
}

Так вы сможете в дальнейшем получать файл по метаполю записи. Для более сложных связей можно использовать set_post_thumbnail для установки изображения записи.

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

Clearfy Pro — помогает оптимизировать и обезопасить REST API, отключая ненужные эндпоинты и улучшая безопасность.
WPCommunity — расширяет REST API для кастомных типов записей и пользовательских полей, упрощая работу с кастомизацией.

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

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

Проверяйте права пользователя, чтобы только авторизованные пользователи могли загружать файлы.
Ограничивайте типы и размеры загружаемых файлов, чтобы избежать загрузки опасных скриптов.
Используйте функции WordPress для обработки загрузки — они уже содержат много проверок и защит.
Логируйте ошибки и попытки загрузки, чтобы быстро реагировать на возможные атаки.

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

Выводы и применение на практике

Добавление обработки файлов в собственные REST API маршруты WordPress — задача, которая требует понимания работы с multipart/form-data, загрузки файлов и создания вложений. Использование приведённых примеров кода позволит быстро создать надёжный и безопасный функционал загрузки файлов. В дальнейшем можно расширять функционал, добавляя валидацию, связь с кастомными типами записей и обработку нескольких файлов.

Если вы хотите автоматизировать отчёты или интегрировать загрузку файлов с другими задачами, рекомендуем обратить внимание на плагин Expert Review, который позволяет создавать автоматические отчёты и отзывы, что может дополнить функционал вашего сайта.