wp_unique_filename

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

Если файл в таким именем существует в директории, то функция добавит в конец имени файла число и проверит новое имя. И так до тех пор, пока имя не станет уникальным. Функция вернет уникальное имя файла.

В третий параметр функции $unique_filename_callback можно передать название функции, которая будет уникализировать имя файла. По умолчанию к названию файла прибавляются цифры: name1.jpg, name2.jpg и т.д.

Заметка: wp_unique_filename() автоматически использует, функцию очистки имени файла sanitize_file_name().
Хуки из функции:
wp_unique_filename
Возвращает

Строку: новое имя файла (не путь), если текущее имя не уникально или возвращает переданное имя.

Использование

wp_unique_filename( $dir, $filename, $unique_filename_callback );
$dir(строка) (обязательный)
Путь до каталога (директории), в котором находится файл.
$filename(строка) (обязательный)
Имя файла (только имя, не путь с именем), который нужно проверить на уникальность.
$unique_filename_callback(callback)
Название функции, которая будет проверять уникальность. По умолчанию – встроенная функция.
По умолчанию: null

Примеры

#1 Уникализируем имя файла перед сохранением его в каталог

Допустим мы сохраняем файл file.jpg в каталог /home/files и там уже есть файл с таким именем. Тогда, чтобы не перезаписать имеющийся файл новым, а добавить новый файл, мы можем создать новое уникальное имя налету, так:

<?php
function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) {
	// Sanitize the file name before we begin processing.
	$filename = sanitize_file_name($filename);

	// Separate the filename into a name and extension.
	$ext = pathinfo( $filename, PATHINFO_EXTENSION );
	$name = pathinfo( $filename, PATHINFO_BASENAME );
	if ( $ext ) {
		$ext = '.' . $ext;
	}

	// Edge case: if file is named '.ext', treat as an empty name.
	if ( $name === $ext ) {
		$name = '';
	}

	/*
	 * Increment the file number until we have a unique file to save in $dir.
	 * Use callback if supplied.
	 */
	if ( $unique_filename_callback && is_callable( $unique_filename_callback ) ) {
		$filename = call_user_func( $unique_filename_callback, $dir, $name, $ext );
	} else {
		$number = '';

		// Change '.ext' to lower case.
		if ( $ext && strtolower($ext) != $ext ) {
			$ext2 = strtolower($ext);
			$filename2 = preg_replace( '|' . preg_quote($ext) . '$|', $ext2, $filename );

			// Check for both lower and upper case extension or image sub-sizes may be overwritten.
			while ( file_exists($dir . "/$filename") || file_exists($dir . "/$filename2") ) {
				$new_number = $number + 1;
				$filename = str_replace( array( "-$number$ext", "$number$ext" ), "-$new_number$ext", $filename );
				$filename2 = str_replace( array( "-$number$ext2", "$number$ext2" ), "-$new_number$ext2", $filename2 );
				$number = $new_number;
			}

			/**
			 * Filters the result when generating a unique file name.
			 *
			 * @since 4.5.0
			 *
			 * @param string        $filename                 Unique file name.
			 * @param string        $ext                      File extension, eg. ".png".
			 * @param string        $dir                      Directory path.
			 * @param callable|null $unique_filename_callback Callback function that generates the unique file name.
			 */
			return apply_filters( 'wp_unique_filename', $filename2, $ext, $dir, $unique_filename_callback );
		}

		while ( file_exists( $dir . "/$filename" ) ) {
			if ( '' == "$number$ext" ) {
				$filename = "$filename-" . ++$number;
			} else {
				$filename = str_replace( array( "-$number$ext", "$number$ext" ), "-" . ++$number . $ext, $filename );
			}
		}
	}

	/** This filter is documented in wp-includes/functions.php */
	return apply_filters( 'wp_unique_filename', $filename, $ext, $dir, $unique_filename_callback );
}