Как создать нетипичный файловый хендлер в WordPress для обработки нестандартных типов файлов

Автор: Диана Романова | Опубликовано: 24.03.2026

WordPress из коробки поддерживает работу с популярными типами файлов, такими как изображения, видео, аудио и документы. Однако время от времени возникает задача загрузить и обработать нестандартные форматы файлов, например, .svg, .json, .webp, .heic или даже собственные форматы. В этой статье мы рассмотрим, как создать собственный файловый хендлер (обработчик) для таких форматов, которые WordPress по умолчанию не поддерживает.

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

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

Обычно для этого достаточно добавить MIME-тип в фильтр upload_mimes. Но если нужно не просто разрешить загрузку, а корректно обрабатывать файл (например, конвертировать, отображать в админке, создавать превью) — потребуется создать полноценный хендлер.

Как добавить поддержку нового типа файла через фильтр upload_mimes

Самый простой шаг — расширить список допустимых MIME-типов. Например, для формата .svg:

function wpbono_allow_svg_uploads($mimes) {
    $mimes['svg'] = 'image/svg+xml';
    return $mimes;
}
add_filter('upload_mimes', 'wpbono_allow_svg_uploads');

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

Создание кастомного файлового хендлера: пример с форматом .json

Допустим, нам нужно загружать и работать с файлами .json, например, для импорта настроек или данных. Для этого:

Добавим поддержку MIME типа.
Создадим функцию, которая при загрузке будет проверять и валидировать JSON.
Реализуем вывод пользовательского превью в админке.

1. Добавление MIME типа JSON

function wpbono_allow_json_uploads($mimes) {
    $mimes['json'] = 'application/json';
    return $mimes;
}
add_filter('upload_mimes', 'wpbono_allow_json_uploads');

2. Валидация JSON при загрузке

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

function wpbono_validate_json_upload($file) {
    if (isset($file['name']) && pathinfo($file['name'], PATHINFO_EXTENSION) === 'json') {
        $content = file_get_contents($file['tmp_name']);
        json_decode($content);
        if (json_last_error() !== JSON_ERROR_NONE) {
            $file['error'] = 'Загруженный файл JSON содержит ошибки и не может быть использован.';
        }
    }
    return $file;
}
add_filter('wp_handle_upload_prefilter', 'wpbono_validate_json_upload');

3. Пользовательский предпросмотр JSON в медиабиблиотеке

Для удобства можно выводить часть содержимого JSON под миниатюрой файла. Это требует добавления к метаданным файла и фильтра вывода.

function wpbono_add_json_preview($metadata, $attachment_id) {
    $file_path = get_attached_file($attachment_id);
    if (pathinfo($file_path, PATHINFO_EXTENSION) === 'json') {
        $content = file_get_contents($file_path);
        $data = json_decode($content, true);
        if ($data && is_array($data)) {
            $preview = esc_html(print_r(array_slice($data, 0, 3), true));
            update_post_meta($attachment_id, '_wpbono_json_preview', $preview);
        }
    }
    return $metadata;
}
add_filter('wp_generate_attachment_metadata', 'wpbono_add_json_preview', 10, 2);

function wpbono_show_json_preview($response, $attachment, $meta) {
    if ($attachment->post_mime_type === 'application/json') {
        $preview = get_post_meta($attachment->ID, '_wpbono_json_preview', true);
        if ($preview) {
            $response['json_preview'] = '<pre style="max-height:100px; overflow:auto; background:#f7f7f7; padding:10px;">' . $preview . '</pre>';
        }
    }
    return $response;
}
add_filter('wp_prepare_attachment_for_js', 'wpbono_show_json_preview', 10, 3);

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

Расширение: создание кастомного плагина для управления загрузками

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

В плагине можно использовать фильтры и хуки для:

Добавления новых MIME типов
Валидации и очистки данных
Автоматической обработки (конвертации, оптимизации)
Создания пользовательских метаданных и превью

Пример заголовка плагина:

/*
Plugin Name: WPBono Custom File Handler
Description: Добавляет поддержку нестандартных форматов файлов с валидацией и предпросмотром.
Version: 1.0
Author: WPBono
*/

Примеры плагинов для работы с мультимедиа и расширения загрузок

Если вы не хотите писать все с нуля, стоит обратить внимание на следующие плагины:

Clearfy Pro — содержит модули для расширения безопасности и управления загрузками.
WPRemark — улучшает работу с медиа, комментированием и метаданными.

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

Особенности безопасности при работе с новыми типами файлов

Обязательно внимательно проверяйте загружаемые файлы, особенно если это исполняемые или текстовые форматы. Например, SVG-файлы могут содержать вредоносный код. Для JSON стоит валидировать структуру, а для других форматов — использовать специальные библиотеки.

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

Заключение: советы по созданию файлового хендлера в WordPress

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

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