sanitize_file_name

Sanitizes a filename, replacing whitespace with dashes.

Description

(string) sanitize_file_name( (string) $filename );

Removes special characters that are illegal in filenames on certain operating systems and special characters requiring special escaping to manipulate at the command line. Replaces spaces and consecutive dashes with a single dash. Trims period, dash and underscore from beginning and end of filename. It is not guaranteed that this function will return a filename that is allowed to be uploaded.

Returns (string)

The sanitized filename

Parameters (1)

0. $filename (string): The filename to be sanitized

Usage

if ( !function_exists( 'sanitize_file_name' ) ) { 
    require_once ABSPATH . WPINC . '/formatting.php'; 
} 
  
// The filename to be sanitized 
$filename = ''; 
  
// NOTICE! Understand what this does before running. 
$result = sanitize_file_name($filename);

Defined (1)

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

/wp-includes/formatting.php

function sanitize_file_name( $filename ) { 
    $filename_raw = $filename; 
    $special_chars = array("?", "[", "]", "/", "\\", "=", "<", ">", ":", ";", ", ", "'", "\"", "&", "$", "#", "*", "(", ")", "|", "~", "`", "!", "{", "}", "%", "+", chr(0)); 
    /** 
     * Filters the list of characters to remove from a filename. 
     * 
     * @since 2.8.0 
     * 
     * @param array  $special_chars Characters to remove. 
     * @param string $filename_raw  Filename as it was passed into sanitize_file_name(). 
     */ 
    $special_chars = apply_filters( 'sanitize_file_name_chars', $special_chars, $filename_raw ); 
    $filename = preg_replace( "#\x{00a0}#siu", ' ', $filename ); 
    $filename = str_replace( $special_chars, '', $filename ); 
    $filename = str_replace( array( '%20', '+' ), '-', $filename ); 
    $filename = preg_replace( '/[\r\n\t -]+/', '-', $filename ); 
    $filename = trim( $filename, '.-_' ); 
 
    if ( false === strpos( $filename, '.' ) ) { 
        $mime_types = wp_get_mime_types(); 
        $filetype = wp_check_filetype( 'test.' . $filename, $mime_types ); 
        if ( $filetype['ext'] === $filename ) { 
            $filename = 'unnamed-file.' . $filetype['ext']; 
        } 
    } 
 
    // Split the filename into a base and extension[s] 
    $parts = explode('.', $filename); 
 
    // Return if only one extension 
    if ( count( $parts ) <= 2 ) { 
        /** 
         * Filters a sanitized filename string. 
         * 
         * @since 2.8.0 
         * 
         * @param string $filename     Sanitized filename. 
         * @param string $filename_raw The filename prior to sanitization. 
         */ 
        return apply_filters( 'sanitize_file_name', $filename, $filename_raw ); 
    } 
 
    // Process multiple extensions 
    $filename = array_shift($parts); 
    $extension = array_pop($parts); 
    $mimes = get_allowed_mime_types(); 
 
    /** 
     * Loop over any intermediate extensions. Postfix them with a trailing underscore 
     * if they are a 2 - 5 character long alpha string not in the extension whitelist. 
     */ 
    foreach ( (array) $parts as $part) { 
        $filename .= '.' . $part; 
 
        if ( preg_match("/^[a-zA-Z]{2, 5}\d?$/", $part) ) { 
            $allowed = false; 
            foreach ( $mimes as $ext_preg => $mime_match ) { 
                $ext_preg = '!^(' . $ext_preg . ')$!i'; 
                if ( preg_match( $ext_preg, $part ) ) { 
                    $allowed = true; 
                    break; 
                } 
            } 
            if ( !$allowed ) 
                $filename .= '_'; 
        } 
    } 
    $filename .= '.' . $extension; 
    /** This filter is documented in wp-includes/formatting.php */ 
    return apply_filters('sanitize_file_name', $filename, $filename_raw); 
}