Функция wp_unique_filename() используется в WordPress для генерации уникальных имен файлов перед их сохранением в указанную директорию. Эта функция особенно полезна, когда нужно предотвратить перезапись существующих файлов. Если файл с указанным именем уже существует, к имени добавляется числовой суффикс, пока не будет найдено уникальное имя.
wp_unique_filename( string $dir, string $filename, callable $unique_filename_callback = null ): string
Параметры:
$dir(строка, обязательный): Директория, в которой проверяется наличие файла.$filename(строка, обязательный): Имя файла (с расширением), которое необходимо уникализировать.$unique_filename_callback(callable, необязательный): Функция обратного вызова для кастомного уникализирования имени. Если не указано, используется стандартный метод добавления чисел к имени файла.
Возвращаемое значение:
Функция возвращает строку — уникальное имя файла. Если указанный файл уже существует, к его имени будет добавлен суффикс в виде числа, и так до тех пор, пока имя не станет уникальным.
Как работает wp_unique_filename()
При сохранении файла с именем, которое уже используется в директории, WordPress автоматически добавляет к имени число (например, file1.jpg, file2.jpg и т.д.), пока не будет найдено уникальное имя.
Функция также использует sanitize_file_name() для очистки имени файла, чтобы избежать проблем с недопустимыми символами.
Пример 1: Генерация уникального имени файла перед сохранением
Предположим, вы хотите сохранить файл с именем document.pdf в папку /home/uploads. Если файл с таким именем уже существует, функция сгенерирует новое уникальное имя для файла.
$filename = 'document.pdf';
$directory = '/home/uploads';
$unique_filename = wp_unique_filename( $directory, $filename );
echo $unique_filename; // Например: document1.pdf
В данном случае, если в папке уже существует файл document.pdf, функция вернет document1.pdf, если же и это имя занято — то document2.pdf, и так далее.
Пример 2: Создание уникального имени для изображения
Допустим, вы загружаете изображение на сайт через форму, и оно должно быть сохранено в директорию загрузок. Мы можем убедиться, что имя загружаемого изображения уникально.
$image_name = 'photo.jpg';
$upload_dir = wp_upload_dir();
$upload_path = $upload_dir['path']; // Получаем текущую папку загрузок
$unique_image_name = wp_unique_filename( $upload_path, $image_name );
echo $unique_image_name; // Например: photo2.jpg
Этот код сначала получает путь к директории загрузок с помощью wp_upload_dir(), а затем проверяет уникальность имени файла. Если в папке уже существует файл с именем photo.jpg, функция вернет уникальное имя, например, photo2.jpg.
Пример 3: Использование пользовательской функции для уникализации имени
Иногда может потребоваться более сложная логика для создания уникальных имен файлов. Например, вы хотите, чтобы вместо чисел в суффиксе использовалась дата.
function custom_unique_filename( $dir, $name, $ext ) {
$date_suffix = date('Ymd');
$new_name = "{$name}-{$date_suffix}{$ext}";
// Проверим, существует ли файл
if ( file_exists( $dir . '/' . $new_name ) ) {
$new_name = "{$name}-{$date_suffix}-1{$ext}";
}
return $new_name;
}
$filename = 'report.pdf';
$directory = '/home/reports';
$unique_filename = wp_unique_filename( $directory, $filename, 'custom_unique_filename' );
echo $unique_filename; // Например: report-20241019.pdf
В этом примере пользовательская функция добавляет к имени файла текущую дату в формате ГГГГММДД. Если файл с таким именем уже существует, добавляется суффикс -1.
Важные моменты
- Автоматическая очистка имени файла: Функция использует
sanitize_file_name()для удаления пробелов, недопустимых символов и приведения имени файла к безопасному формату. - Настраиваемые алгоритмы уникализации: Через третий параметр можно передать пользовательскую функцию для создания уникальных имен файлов с кастомной логикой.
Заключение
Функция wp_unique_filename() — это удобный инструмент для предотвращения конфликтов при сохранении файлов в WordPress. Она помогает избежать перезаписи файлов, автоматически добавляя уникальные суффиксы к именам. Важно помнить, что функция по умолчанию работает с простым алгоритмом добавления чисел, но может быть расширена пользовательскими функциями для создания более сложных вариантов именования.