Как использовать wp_upload_dir() в WordPress для правильного хранения файлов

Функция wp_upload_dir() — это один из самых важных инструментов для разработчиков, которые работают с загрузкой и хранением файлов в WordPress. Она возвращает массив с путями и URL-адресами к директории загрузок, что позволяет корректно сохранять и получать файлы в любой теме или плагине. В этой статье разберём, как правильно использовать эту функцию, какие у неё есть особенности и как избежать типичных ошибок при работе с файлами.

Что возвращает функция wp_upload_dir() и какие данные в ней есть

При вызове wp_upload_dir() вы получаете ассоциативный массив с такими ключами:

path — физический путь на сервере к директории текущей загрузки (например, /var/www/site/wp-content/uploads/2024/06);
url — URL к директории загрузок (например, https://site.ru/wp-content/uploads/2024/06);
subdir — поддиректория внутри папки загрузок, обычно в формате /год/месяц;
basedir — базовый путь к папке uploads, без поддиректорий (например, /var/www/site/wp-content/uploads);
baseurl — базовый URL папки uploads (например, https://site.ru/wp-content/uploads);
error — строка с ошибкой или false, если ошибок нет.

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

Как использовать wp_upload_dir() для сохранения пользовательских файлов

Предположим, вам нужно загрузить файл, полученный через форму на сайте, и сохранить его в папку uploads с сохранением текущей даты. Вот как можно это сделать:

function wpfix_save_uploaded_file($file) {
    $upload_dir = wp_upload_dir();
    if ($upload_dir['error']) {
        return new WP_Error('upload_dir_error', $upload_dir['error']);
    }

    $target_dir = $upload_dir['path']; // директория с текущим годом и месяцем
    if (!file_exists($target_dir)) {
        wp_mkdir_p($target_dir); // создаём директорию, если её нет
    }

    $filename = sanitize_file_name($file['name']);
    $target_file = $target_dir . '/' . $filename;

    if (move_uploaded_file($file['tmp_name'], $target_file)) {
        $file_url = $upload_dir['url'] . '/' . $filename;
        return $file_url; // Возвращаем URL к загруженному файлу
    } else {
        return new WP_Error('upload_error', 'Не удалось переместить загруженный файл.');
    }
}

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

Как изменить директорию загрузок с помощью фильтра upload_dir

В некоторых случаях может потребоваться изменить стандартный путь загрузок, например, для хранения файлов в отдельной папке или на другом диске. Для этого используется фильтр upload_dir. Рассмотрим пример, в котором все загружаемые файлы сохраняются в поддиректории /custom_uploads внутри uploads:

add_filter('upload_dir', 'wpfix_custom_upload_dir');
function wpfix_custom_upload_dir($dirs) {
    $dirs['path'] = str_replace('/uploads', '/uploads/custom_uploads', $dirs['path']);
    $dirs['url'] = str_replace('/uploads', '/uploads/custom_uploads', $dirs['url']);
    $dirs['basedir'] = str_replace('/uploads', '/uploads/custom_uploads', $dirs['basedir']);
    $dirs['baseurl'] = str_replace('/uploads', '/uploads/custom_uploads', $dirs['baseurl']);
    $dirs['subdir'] = str_replace('/uploads', '/uploads/custom_uploads', $dirs['subdir']);
    return $dirs;
}

После добавления этого фильтра все функции, использующие wp_upload_dir(), будут обращаться к изменённой директории. Это полезно, если вы хотите разделить файлы по типам или проектам.

Решение распространённых ошибок при работе с wp_upload_dir()

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

Убедитесь, что папка wp-content/uploads и её поддиректории имеют права на запись для веб-сервера (обычно 755 или 775).
Всегда проверяйте возвращаемое значение error из wp_upload_dir() — если там есть сообщение, значит путь недоступен или нет прав.
Используйте встроенную функцию wp_mkdir_p() для создания директорий, она учитывает особенности ОС и WordPress.
Для безопасности всегда применяйте sanitize_file_name() к именам файлов перед сохранением.

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

Пример плагина для загрузки и отображения файлов с использованием wp_upload_dir()

Предлагаю простой пример плагина, который добавляет в админке форму для загрузки файлов и выводит список загруженных файлов с их URL:

/**
 * Plugin Name: WPFix File Manager
 */

add_action('admin_menu', function() {
    add_menu_page('WPFix Files', 'WPFix Files', 'manage_options', 'wpfix-files', 'wpfix_files_page');
});

function wpfix_files_page() {
    if (!empty($_FILES['wpfix_file']['name'])) {
        $result = wpfix_save_uploaded_file($_FILES['wpfix_file']);
        if (is_wp_error($result)) {
            echo '<div style="color:red;">' . esc_html($result->get_error_message()) . '</div>';
        } else {
            echo '<div style="color:green;">Файл загружен: <a href="' . esc_url($result) . '" target="_blank">' . esc_html($result) . '</a></div>';
        }
    }

    echo '<h2>Загрузить файл</h2>';
    echo '<form method="post" enctype="multipart/form-data">';
    echo '<input type="file" name="wpfix_file" required>';
    echo '<input type="submit" value="Загрузить">';
    echo '</form>';

    $upload_dir = wp_upload_dir();
    $files = glob($upload_dir['path'] . '/*');
    if ($files) {
        echo '<h3>Список загруженных файлов</h3><ul>';
        foreach ($files as $file) {
            $url = $upload_dir['url'] . '/' . basename($file);
            echo '<li><a href="' . esc_url($url) . '" target="_blank">' . esc_html(basename($file)) . '</a></li>';
        }
        echo '</ul>';
    } else {
        echo '<p>Файлы не найдены.</p>';
    }
}

function wpfix_save_uploaded_file($file) {
    $upload_dir = wp_upload_dir();
    if ($upload_dir['error']) {
        return new WP_Error('upload_dir_error', $upload_dir['error']);
    }

    $target_dir = $upload_dir['path'];
    if (!file_exists($target_dir)) {
        wp_mkdir_p($target_dir);
    }

    $filename = sanitize_file_name($file['name']);
    $target_file = $target_dir . '/' . $filename;

    if (move_uploaded_file($file['tmp_name'], $target_file)) {
        return $upload_dir['url'] . '/' . $filename;
    } else {
        return new WP_Error('upload_error', 'Не удалось переместить загруженный файл.');
    }
}

Этот пример поможет понять, как использовать wp_upload_dir() в реальных задачах.

Заключение по работе с wp_upload_dir()

Функция wp_upload_dir() — это ключ к правильной и безопасной работе с файлами в WordPress. Она учитывает структуру сайта, настройки и дату, позволяя создавать универсальные решения для плагинов и тем. Используйте её совместно с фильтром upload_dir для гибкой настройки путей и всегда проверяйте возвращаемые данные и права доступа.