wp_unique_filename() WP 2.5.0

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

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

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

Возвращает

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

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

wp_unique_filename( $dir, $filename, $unique_filename_callback );

$dir(строка) (обязательный)

Путь до каталога (директории), в котором находится файл.

$filename(строка) (обязательный)

Имя файла (только имя, не путь с именем), который нужно проверить на уникальность.

$unique_filename_callback(callback)

Название функции, которая будет проверять уникальность. По умолчанию - встроенная функция.
По умолчанию: null

Примеры

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

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

$file = 'file.jpg';
$file = wp_unique_filename( '/home/files', $file );
echo $file; //> file1.jpg

Список изменений

Код wp unique filename: wp-includes/functions.php ^{WP 5.3}

<?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 = (int) $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" ) ) {
			$new_number = (int) $number + 1;
			if ( '' == "$number$ext" ) {
				$filename = "$filename-" . $new_number;
			} else {
				$filename = str_replace( array( "-$number$ext", "$number$ext" ), '-' . $new_number . $ext, $filename );
			}
			$number = $new_number;
		}
	}

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

Cвязанные функции

Из раздела: Загрузка (download upload)