wp_unique_filename

Get a filename that is sanitized and unique for the given directory.

Description

(string) wp_unique_filename( (string) $dir, (string) $filename, (null) $unique_filename_callback = null ); 

If the filename is not unique, then a number will be added to the filename before the extension, and will continue adding numbers until the filename is unique.

The callback is passed three parameters, the first one is the directory, the second is the filename, and the third is the extension.

Returns (string)

New filename, if given wasn't unique.

Parameters (3)

0. $dir (string)
Directory.
1. $filename (string)
The filename.
2. $unique_filename_callback — Optional. (null) => null
The unique filename callback.

Usage

  1. if ( !function_exists( 'wp_unique_filename' ) ) { 
  2. require_once ABSPATH . WPINC . '/functions.php'; 
  3.  
  4. // Directory. 
  5. $dir = ''; 
  6.  
  7. // The filename. 
  8. $filename = ''; 
  9.  
  10. // The unique filename callback. 
  11. $unique_filename_callback = null; 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = wp_unique_filename($dir, $filename, $unique_filename_callback); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/functions.php  
  1. function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) { 
  2. // Sanitize the file name before we begin processing. 
  3. $filename = sanitize_file_name($filename); 
  4.  
  5. // Separate the filename into a name and extension. 
  6. $ext = pathinfo( $filename, PATHINFO_EXTENSION ); 
  7. $name = pathinfo( $filename, PATHINFO_BASENAME ); 
  8. if ( $ext ) { 
  9. $ext = '.' . $ext; 
  10.  
  11. // Edge case: if file is named '.ext', treat as an empty name. 
  12. if ( $name === $ext ) { 
  13. $name = ''; 
  14.  
  15. /** 
  16. * Increment the file number until we have a unique file to save in $dir. 
  17. * Use callback if supplied. 
  18. */ 
  19. if ( $unique_filename_callback && is_callable( $unique_filename_callback ) ) { 
  20. $filename = call_user_func( $unique_filename_callback, $dir, $name, $ext ); 
  21. } else { 
  22. $number = ''; 
  23.  
  24. // Change '.ext' to lower case. 
  25. if ( $ext && strtolower($ext) != $ext ) { 
  26. $ext2 = strtolower($ext); 
  27. $filename2 = preg_replace( '|' . preg_quote($ext) . '$|', $ext2, $filename ); 
  28.  
  29. // Check for both lower and upper case extension or image sub-sizes may be overwritten. 
  30. while ( file_exists($dir . "/$filename") || file_exists($dir . "/$filename2") ) { 
  31. $new_number = (int) $number + 1; 
  32. $filename = str_replace( array( "-$number$ext", "$number$ext" ), "-$new_number$ext", $filename ); 
  33. $filename2 = str_replace( array( "-$number$ext2", "$number$ext2" ), "-$new_number$ext2", $filename2 ); 
  34. $number = $new_number; 
  35.  
  36. /** 
  37. * Filters the result when generating a unique file name. 
  38. * @since 4.5.0 
  39. * @param string $filename Unique file name. 
  40. * @param string $ext File extension, eg. ".png". 
  41. * @param string $dir Directory path. 
  42. * @param callable|null $unique_filename_callback Callback function that generates the unique file name. 
  43. */ 
  44. return apply_filters( 'wp_unique_filename', $filename2, $ext, $dir, $unique_filename_callback ); 
  45.  
  46. while ( file_exists( $dir . "/$filename" ) ) { 
  47. $new_number = (int) $number + 1; 
  48. if ( '' == "$number$ext" ) { 
  49. $filename = "$filename-" . $new_number; 
  50. } else { 
  51. $filename = str_replace( array( "-$number$ext", "$number$ext" ), "-" . $new_number . $ext, $filename ); 
  52. $number = $new_number; 
  53.  
  54. /** This filter is documented in wp-includes/functions.php */ 
  55. return apply_filters( 'wp_unique_filename', $filename, $ext, $dir, $unique_filename_callback );