Using WordPress ‘pre_wp_unique_filename_file_list’ PHP filter

by

‘pre_wp_unique_filename_file_list’ is a WordPress PHP filter that allows you to modify the file list used for calculating a unique filename for a newly added file.

By returning an array from the filter, you can bypass the default retrieval from the filesystem and use the provided value instead.

Usage

add_filter( 'pre_wp_unique_filename_file_list', 'my_custom_file_list', 10, 3 );

function my_custom_file_list( $files, $dir, $filename ) {
    // Your custom logic here
}

Parameters

  • $files array|null
    • The list of files to use for filename comparisons.
    • Default: null (to retrieve the list from the filesystem).
  • $dir string
    • The directory for the new file.
  • $filename string
    • The proposed filename for the new file.

Examples

Preventing Filename Conflicts with Custom File List

add_filter( 'pre_wp_unique_filename_file_list', 'prevent_filename_conflicts', 10, 3 );

function prevent_filename_conflicts( $files, $dir, $filename ) {
    $custom_file_list = array( 'file1.jpg', 'file2.jpg', 'file3.jpg' );

    return $custom_file_list;
}

In this example, we provide a custom file list to avoid conflicts with the existing files. The new file will be given a unique filename based on the provided custom file list.

Excluding Files with Specific Extensions

add_filter( 'pre_wp_unique_filename_file_list', 'exclude_files_with_extensions', 10, 3 );

function exclude_files_with_extensions( $files, $dir, $filename ) {
    $allowed_files = array_filter( $files, function( $file ) {
        return ! preg_match( '/.(txt|pdf)$/', $file );
    });

    return $allowed_files;
}

In this example, we exclude files with “.txt” and “.pdf” extensions from the file list. This prevents the new file from having a unique filename based on the excluded file types.

Using Files from a Custom Directory

add_filter( 'pre_wp_unique_filename_file_list', 'use_custom_directory', 10, 3 );

function use_custom_directory( $files, $dir, $filename ) {
    $custom_dir = '/path/to/custom/directory';
    $custom_files = scandir( $custom_dir );

    return $custom_files;
}

Here, we use a custom directory for the file list. The new file will be given a unique filename based on the files in the custom directory.

Adding a Prefix to Filenames

add_filter( 'pre_wp_unique_filename_file_list', 'add_filename_prefix', 10, 3 );

function add_filename_prefix( $files, $dir, $filename ) {
    $prefixed_files = array_map( function( $file ) {
        return 'prefix_' . $file;
    }, $files );

    return $prefixed_files;
}

In this example, we add a prefix to the filenames in the file list. The new file will be given a unique filename based on the prefixed filenames.

Filtering Files by Modified Time

add_filter( 'pre_wp_unique_filename_file_list', 'filter_files_by_modified_time', 10, 3 );
function filter_files_by_modified_time( $files, $dir, $filename ) {
$threshold = strtotime( '-30 days' );
$filtered_files = array_filter($files, function($file) use ($dir, $threshold) {
$file_path = $dir . '/' . $file;
return (filemtime($file_path) >= $threshold);
});
return $filtered_files;

In this example, we filter the files in the file list based on their modified time. The new file will be given a unique filename considering only the files modified within the last 30 days.