wp_unique_filename() WordPress Function

The wp_unique_filename() function is used to generate a unique filename for a given file. This function is used by the WordPress media uploader to ensure that each file has a unique name when it is uploaded to the server.

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

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

Description
Parameters
Return
Source
Related
- Uses
- Used By
Changelog

Description

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 function allows the caller to use their own method to create unique file names. If defined, the callback should take three arguments:

directory, base filename, and extension – and return a unique filename.

Top ↑

Parameters

$dir

(string)(Required)Directory.

$filename

(string)(Required)File name.

$unique_filename_callback

(callable)(Optional)Callback.

Default value: null

Top ↑

Return

(string) New filename, if given wasn't unique.

Top ↑

Source

File: wp-includes/functions.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;
 
    // Initialize vars used in the wp_unique_filename filter.
    $number        = '';
    $alt_filenames = array();
 
    // 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 {
        $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 );
        }
 
        /*
         * Get the mime type. Uploaded files were already checked with wp_check_filetype_and_ext()
         * in _wp_handle_upload(). Using wp_check_filetype() would be sufficient here.
         */
        $file_type = wp_check_filetype( $filename );
        $mime_type = $file_type['type'];
 
        $is_image    = ( ! empty( $mime_type ) && 0 === strpos( $mime_type, 'image/' ) );
        $upload_dir  = wp_get_upload_dir();
        $lc_filename = null;
 
        $lc_ext = strtolower( $ext );
        $_dir   = trailingslashit( $dir );
 
        /*
         * If the extension is uppercase add an alternate file name with lowercase extension.
         * Both need to be tested for uniqueness as the extension will be changed to lowercase
         * for better compatibility with different filesystems. Fixes an inconsistency in WP < 2.9
         * where uppercase extensions were allowed but image sub-sizes were created with
         * lowercase extensions.
         */
        if ( $ext && $lc_ext !== $ext ) {
            $lc_filename = preg_replace( '|' . preg_quote( $ext ) . '$|', $lc_ext, $filename );
        }
 
        /*
         * Increment the number added to the file name if there are any files in $dir
         * whose names match one of the possible name variations.
         */
        while ( file_exists( $_dir . $filename ) || ( $lc_filename && file_exists( $_dir . $lc_filename ) ) ) {
            $new_number = (int) $number + 1;
 
            if ( $lc_filename ) {
                $lc_filename = str_replace(
                    array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ),
                    "-{$new_number}{$lc_ext}",
                    $lc_filename
                );
            }
 
            if ( '' === "{$number}{$ext}" ) {
                $filename = "{$filename}-{$new_number}";
            } else {
                $filename = str_replace(
                    array( "-{$number}{$ext}", "{$number}{$ext}" ),
                    "-{$new_number}{$ext}",
                    $filename
                );
            }
 
            $number = $new_number;
        }
 
        // Change the extension to lowercase if needed.
        if ( $lc_filename ) {
            $filename = $lc_filename;
        }
 
        /*
         * Prevent collisions with existing file names that contain dimension-like strings
         * (whether they are subsizes or originals uploaded prior to #42437).
         */
 
        $files = array();
        $count = 10000;
 
        // 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'] ) ) {
            /**
             * Filters the file list used for calculating a unique filename for a newly added file.
             *
             * Returning an array from the filter will effectively short-circuit retrieval
             * from the filesystem and return the passed value instead.
             *
             * @since 5.5.0
             *
             * @param array|null $files    The list of files to use for filename comparisons.
             *                             Default null (to retrieve the list from the filesystem).
             * @param string     $dir      The directory for the new file.
             * @param string     $filename The proposed filename for the new file.
             */
            $files = apply_filters( 'pre_wp_unique_filename_file_list', null, $dir, $filename );
 
            if ( null === $files ) {
                // 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 ) ) {
                $count = count( $files );
 
                /*
                 * Ensure this never goes into infinite loop as it uses pathinfo() and regex in the check,
                 * but string replacement for the changes.
                 */
                $i = 0;
 
                while ( $i <= $count && _wp_check_existing_file_names( $filename, $files ) ) {
                    $new_number = (int) $number + 1;
 
                    // If $ext is uppercase it was replaced with the lowercase version after the previous loop.
                    $filename = str_replace(
                        array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ),
                        "-{$new_number}{$lc_ext}",
                        $filename
                    );
 
                    $number = $new_number;
                    $i++;
                }
            }
        }
 
        /*
         * Check if an image will be converted after uploading or some existing image sub-size file names may conflict
         * when regenerated. If yes, ensure the new file name will be unique and will produce unique sub-sizes.
         */
        if ( $is_image ) {
            /** This filter is documented in wp-includes/class-wp-image-editor.php */
            $output_formats = apply_filters( 'image_editor_output_format', array(), $_dir . $filename, $mime_type );
            $alt_types      = array();
 
            if ( ! empty( $output_formats[ $mime_type ] ) ) {
                // The image will be converted to this format/mime type.
                $alt_mime_type = $output_formats[ $mime_type ];
 
                // Other types of images whose names may conflict if their sub-sizes are regenerated.
                $alt_types   = array_keys( array_intersect( $output_formats, array( $mime_type, $alt_mime_type ) ) );
                $alt_types[] = $alt_mime_type;
            } elseif ( ! empty( $output_formats ) ) {
                $alt_types = array_keys( array_intersect( $output_formats, array( $mime_type ) ) );
            }
 
            // Remove duplicates and the original mime type. It will be added later if needed.
            $alt_types = array_unique( array_diff( $alt_types, array( $mime_type ) ) );
 
            foreach ( $alt_types as $alt_type ) {
                $alt_ext = wp_get_default_extension_for_mime_type( $alt_type );
 
                if ( ! $alt_ext ) {
                    continue;
                }
 
                $alt_ext      = ".{$alt_ext}";
                $alt_filename = preg_replace( '|' . preg_quote( $lc_ext ) . '$|', $alt_ext, $filename );
 
                $alt_filenames[ $alt_ext ] = $alt_filename;
            }
 
            if ( ! empty( $alt_filenames ) ) {
                /*
                 * Add the original filename. It needs to be checked again
                 * together with the alternate filenames when $number is incremented.
                 */
                $alt_filenames[ $lc_ext ] = $filename;
 
                // Ensure no infinite loop.
                $i = 0;
 
                while ( $i <= $count && _wp_check_alternate_file_names( $alt_filenames, $_dir, $files ) ) {
                    $new_number = (int) $number + 1;
 
                    foreach ( $alt_filenames as $alt_ext => $alt_filename ) {
                        $alt_filenames[ $alt_ext ] = str_replace(
                            array( "-{$number}{$alt_ext}", "{$number}{$alt_ext}" ),
                            "-{$new_number}{$alt_ext}",
                            $alt_filename
                        );
                    }
 
                    /*
                     * Also update the $number in (the output) $filename.
                     * If the extension was uppercase it was already replaced with the lowercase version.
                     */
                    $filename = str_replace(
                        array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ),
                        "-{$new_number}{$lc_ext}",
                        $filename
                    );
 
                    $number = $new_number;
                    $i++;
                }
            }
        }
    }
 
    /**
     * Filters the result when generating a unique file name.
     *
     * @since 4.5.0
     * @since 5.8.1 The `$alt_filenames` and `$number` parameters were added.
     *
     * @param string        $filename                 Unique file name.
     * @param string        $ext                      File extension. Example: ".png".
     * @param string        $dir                      Directory path.
     * @param callable|null $unique_filename_callback Callback function that generates the unique file name.
     * @param string[]      $alt_filenames            Array of alternate file names that were checked for collisions.
     * @param int|string    $number                   The highest number that was used to make the file name unique
     *                                                or an empty string if unused.
     */
    return apply_filters( 'wp_unique_filename', $filename, $ext, $dir, $unique_filename_callback, $alt_filenames, $number );
}

Expand full source code Collapse full source codeView on TracView on GitHub

Top ↑

Uses

Uses
Uses	Description
wp-includes/functions.php:wp_get_default_extension_for_mime_type()	Returns first matched extension for the mime-type, as mapped from wp_get_mime_types().
wp-includes/functions.php:_wp_check_alternate_file_names()	Helper function to test if each of an array of file names could conflict with existing files.
wp-includes/class-wp-image-editor.php:image_editor_output_format	Filters the image editor output format mapping.
wp-includes/functions.php:pre_wp_unique_filename_file_list	Filters the file list used for calculating a unique filename for a newly added file.
wp-includes/functions.php:_wp_check_existing_file_names()	Helper function to check if a file name could match an existing image sub-size file name.
wp-includes/functions.php:wp_unique_filename	Filters the result when generating a unique file name.
wp-includes/functions.php:wp_get_upload_dir()	Retrieves uploads directory information.
wp-includes/formatting.php:trailingslashit()	Appends a trailing slash.
wp-includes/formatting.php:sanitize_file_name()	Sanitizes a filename, replacing whitespace with dashes.
wp-includes/functions.php:wp_check_filetype()	Retrieve the file type from the file name.
wp-includes/plugin.php:apply_filters()	Calls the callback functions that have been added to a filter hook.

Show 6 more uses Hide more uses

Top ↑

Used By

Used By
Used By	Description
wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php:WP_REST_Attachments_Controller::edit_media_item()	Applies edits to a media item and creates a new attachment record.
wp-admin/includes/privacy-tools.php:wp_privacy_generate_personal_data_export_file()	Generate the personal data export file.
wp-admin/includes/file.php:_wp_handle_upload()	Handles PHP uploads in WordPress.
wp-admin/includes/image.php:_copy_image_file()	Copy an existing image file.
wp-admin/includes/image.php:wp_generate_attachment_metadata()	Generate attachment meta data and create image sub-sizes for images.
wp-admin/includes/image.php:wp_crop_image()	Crops an image to a given size.
wp-admin/includes/file.php:wp_tempnam()	Returns a filename of a temporary unique file.
wp-includes/functions.php:wp_upload_bits()	Create a file in the upload folder with given content.