wp_unique_filename( string $dir, string $filename, callable $unique_filename_callback = null ): string

Description

Parameters

$dirstring

Directory.

$filenamestring

File name.

$unique_filename_callbackcallableoptional

Callback. Default null.Default: null

Return

string

New filename, if given wasn't unique.

Hooks fired · 2

2 hooks fire while wp_unique_filename() runs, in this order:

1. 1
   apply_filters( pre_wp_unique_filename_file_list )filterline 2676 (+120 into the body)

   Filters the file list used for calculating a unique filename for a newly added file.

2. 2
   apply_filters( wp_unique_filename )filterline 2800 (+244 into the body)

   Filters the result when generating a unique file name.

Uses · 11

• sanitize_file_name()Sanitizes a filename, replacing whitespace with dashes.
• wp_check_filetype()Retrieves the file type from the file name.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• wp_get_upload_dir()Retrieves uploads directory information.
• trailingslashit()Appends a trailing slash.
• str_contains()Polyfill for `str_contains()` function added in PHP 8.0.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• _wp_check_existing_file_names()Helper function to check if a file name could match an existing image sub-size file name.
• wp_get_image_editor_output_format()Determines the output format for the image editor.
• wp_get_default_extension_for_mime_type()Returns the first matched extension for the mime type, as mapped from wp_get_mime_types().
• _wp_check_alternate_file_names()Helper function to test if each of an array of file names could conflict with existing files.

Used by · 8

• WP_REST_Attachments_Controller::edit_media_item()Applies edits to a media item and creates a new attachment record.
• _copy_image_file()Copies an existing image file.
• _wp_handle_upload()Handles PHP uploads in WordPress.
• wp_crop_image()Crops an image to a given size.
• wp_generate_attachment_metadata()Generates attachment meta data and create image sub-sizes for images.
• wp_privacy_generate_personal_data_export_file()Generate the personal data export file.
• wp_tempnam()Returns a filename of a temporary unique file.
• wp_upload_bits()Creates a file in the upload folder with given content.

Source

View on Trac ↗View on GitHub ↗

2556function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) {2557	// Sanitize the file name before we begin processing.2558	$filename = sanitize_file_name( $filename );2559	$ext2     = null;2560 2561	// Initialize vars used in the wp_unique_filename filter.2562	$number        = '';2563	$alt_filenames = array();2564 2565	// Separate the filename into a name and extension.2566	$ext  = pathinfo( $filename, PATHINFO_EXTENSION );2567	$name = pathinfo( $filename, PATHINFO_BASENAME );2568 2569	if ( $ext ) {2570		$ext = '.' . $ext;2571	}2572 2573	// Edge case: if file is named '.ext', treat as an empty name.2574	if ( $name === $ext ) {2575		$name = '';2576	}2577 2578	/*2579	 * Increment the file number until we have a unique file to save in $dir.2580	 * Use callback if supplied.2581	 */2582	if ( $unique_filename_callback && is_callable( $unique_filename_callback ) ) {2583		$filename = call_user_func( $unique_filename_callback, $dir, $name, $ext );2584	} else {2585		$fname = pathinfo( $filename, PATHINFO_FILENAME );2586 2587		// Always append a number to file names that can potentially match image sub-size file names.2588		if ( $fname && preg_match( '/-(?:\d+x\d+|scaled|rotated)$/', $fname ) ) {2589			$number = 1;2590 2591			// At this point the file name may not be unique. This is tested below and the $number is incremented.2592			$filename = str_replace( "{$fname}{$ext}", "{$fname}-{$number}{$ext}", $filename );2593		}2594 2595		/*2596		 * Get the mime type. Uploaded files were already checked with wp_check_filetype_and_ext()2597		 * in _wp_handle_upload(). Using wp_check_filetype() would be sufficient here.2598		 */2599		$file_type = wp_check_filetype( $filename );2600		$mime_type = $file_type['type'];2601 2602		$is_image    = ( ! empty( $mime_type ) && str_starts_with( $mime_type, 'image/' ) );2603		$upload_dir  = wp_get_upload_dir();2604		$lc_filename = null;2605 2606		$lc_ext = strtolower( $ext );2607		$_dir   = trailingslashit( $dir );2608 2609		/*2610		 * If the extension is uppercase add an alternate file name with lowercase extension.2611		 * Both need to be tested for uniqueness as the extension will be changed to lowercase2612		 * for better compatibility with different filesystems. Fixes an inconsistency in WP < 2.92613		 * where uppercase extensions were allowed but image sub-sizes were created with2614		 * lowercase extensions.2615		 */2616		if ( $ext && $lc_ext !== $ext ) {2617			$lc_filename = preg_replace( '|' . preg_quote( $ext ) . '$|', $lc_ext, $filename );2618		}2619 2620		/*2621		 * Increment the number added to the file name if there are any files in $dir2622		 * whose names match one of the possible name variations.2623		 */2624		while ( file_exists( $_dir . $filename ) || ( $lc_filename && file_exists( $_dir . $lc_filename ) ) ) {2625			$new_number = (int) $number + 1;2626 2627			if ( $lc_filename ) {2628				$lc_filename = str_replace(2629					array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ),2630					"-{$new_number}{$lc_ext}",2631					$lc_filename2632				);2633			}2634 2635			if ( '' === "{$number}{$ext}" ) {

History

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-includes/functions.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.