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.4.2}

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

	// 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 = '';
		$fname  = pathinfo( $filename, PATHINFO_FILENAME );

		// Always append a number to file names that can potentially match image sub-size file names.
		if ( $fname && preg_match( '/-(?:\d+x\d+|scaled|rotated)$/', $fname ) ) {
			$number = 1;

			// At this point the file name may not be unique. This is tested below and the $number is incremented.
			$filename = str_replace( "{$fname}{$ext}", "{$fname}-{$number}{$ext}", $filename );
		}

		// 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;
			}

			$filename = $filename2;
		} else {
			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;
			}
		}

		// Prevent collisions with existing file names that contain dimension-like strings
		// (whether they are subsizes or originals uploaded prior to #42437).
		$upload_dir = wp_get_upload_dir();

		// The (resized) image files would have name and extension, and will be in the uploads dir.
		if ( $name && $ext && @is_dir( $dir ) && false !== strpos( $dir, $upload_dir['basedir'] ) ) {
			// List of all files and directories contained in $dir.
			$files = @scandir( $dir );

			if ( ! empty( $files ) ) {
				// Remove "dot" dirs.
				$files = array_diff( $files, array( '.', '..' ) );
			}

			if ( ! empty( $files ) ) {
				// The extension case may have changed above.
				$new_ext = ! empty( $ext2 ) ? $ext2 : $ext;

				// Ensure this never goes into infinite loop
				// as it uses pathinfo() and regex in the check, but string replacement for the changes.
				$count = count( $files );
				$i     = 0;

				while ( $i <= $count && _wp_check_existing_file_names( $filename, $files ) ) {
					$new_number = (int) $number + 1;
					$filename   = str_replace( array( "-{$number}{$new_ext}", "{$number}{$new_ext}" ), "-{$new_number}{$new_ext}", $filename );
					$number     = $new_number;
					$i++;
				}
			}
		}
	}

	/**
	 * 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', $filename, $ext, $dir, $unique_filename_callback );
}

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

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