wp_upload_dir

Get an array containing the current upload directory's path and url.

Description

(array) wp_upload_dir( (constant) $time = null, (constant) $create_dir = true, (bool) $refresh_cache = false ); 

Checks the upload_path option, which should be from the web root folder, and if it isn't empty it will be used. If it is empty, then the path will be WP_CONTENT_DIR/uploads. If the UPLOADS constant is defined, then it will override the upload_path option and WP_CONTENT_DIR/uploads path.

The upload URL path is set either by the upload_url_path option or by using the WP_CONTENT_URL constant and appending /uploads to the path.

If the uploads_use_yearmonth_folders is set to true (checkbox if checked in the administration settings panel), then the time will be used. The format will be year first and then month.

If the path couldn't be created, then an error will be returned with the key 'error' containing the error message. The error suggests that the parent directory is not writable by the server.

On success, the returned array will have many indices: 'path' - base directory and sub directory or full path to upload directory. 'url' - base url and sub directory or absolute URL to upload directory. 'subdir' - sub directory if uploads use year/month folders option is on. 'basedir' - path without subdir. 'baseurl' - URL path without subdir. 'error' - false or error message.

Returns (array)

See above for description.

Parameters (3)

0. $time — Optional. (constant) => null
Time formatted in yyyy/mm.. Default null.
1. $create_dir — Optional. (constant) => true
Whether to check and create the uploads directory. Default true for backward compatibility.
2. $refresh_cache — Optional. (bool) => false
Whether to refresh the cache. Default false.

Usage

  1. if ( !function_exists( 'wp_upload_dir' ) ) { 
  2. require_once ABSPATH . WPINC . '/functions.php'; 
  3.  
  4. // Optional. Time formatted in 'yyyy/mm'. Default null. 
  5. $time = null; 
  6.  
  7. // Optional. Whether to check and create the uploads directory. 
  8. // Default true for backward compatibility. 
  9. $create_dir = true; 
  10.  
  11. // Optional. Whether to refresh the cache. Default false. 
  12. $refresh_cache = false; 
  13.  
  14. // NOTICE! Understand what this does before running. 
  15. $result = wp_upload_dir($time, $create_dir, $refresh_cache); 
  16.  

Defined (2)

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

/wp-includes/functions.php  
  1. function wp_upload_dir( $time = null, $create_dir = true, $refresh_cache = false ) { 
  2. static $cache = array(), $tested_paths = array(); 
  3.  
  4. $key = sprintf( '%d-%s', get_current_blog_id(), (string) $time ); 
  5.  
  6. if ( $refresh_cache || empty( $cache[ $key ] ) ) { 
  7. $cache[ $key ] = _wp_upload_dir( $time ); 
  8.  
  9. /** 
  10. * Filters the uploads directory data. 
  11. * @since 2.0.0 
  12. * @param array $uploads Array of upload directory data with keys of 'path',  
  13. * 'url', 'subdir, 'basedir', and error. 
  14. */ 
  15. $uploads = apply_filters( 'upload_dir', $cache[ $key ] ); 
  16.  
  17. if ( $create_dir ) { 
  18. $path = $uploads['path']; 
  19.  
  20. if ( array_key_exists( $path, $tested_paths ) ) { 
  21. $uploads[error] = $tested_paths[ $path ]; 
  22. } else { 
  23. if ( ! wp_mkdir_p( $path ) ) { 
  24. if ( 0 === strpos( $uploads['basedir'], ABSPATH ) ) { 
  25. $error_path = str_replace( ABSPATH, '', $uploads['basedir'] ) . $uploads['subdir']; 
  26. } else { 
  27. $error_path = basename( $uploads['basedir'] ) . $uploads['subdir']; 
  28.  
  29. $uploads[error] = sprintf( 
  30. /** translators: %s: directory path */ 
  31. __( 'Unable to create directory %s. Is its parent directory writable by the server?' ),  
  32. esc_html( $error_path ) 
  33. ); 
  34.  
  35. $tested_paths[ $path ] = $uploads[error]; 
  36.  
  37. return $uploads; 
  1. function _wp_upload_dir( $time = null ) { 
  2. $siteurl = get_option( 'siteurl' ); 
  3. $upload_path = trim( get_option( 'upload_path' ) ); 
  4.  
  5. if ( empty( $upload_path ) || 'wp-content/uploads' == $upload_path ) { 
  6. $dir = WP_CONTENT_DIR . '/uploads'; 
  7. } elseif ( 0 !== strpos( $upload_path, ABSPATH ) ) { 
  8. // $dir is absolute, $upload_path is (maybe) relative to ABSPATH 
  9. $dir = path_join( ABSPATH, $upload_path ); 
  10. } else { 
  11. $dir = $upload_path; 
  12.  
  13. if ( !$url = get_option( 'upload_url_path' ) ) { 
  14. if ( empty($upload_path) || ( 'wp-content/uploads' == $upload_path ) || ( $upload_path == $dir ) ) 
  15. $url = WP_CONTENT_URL . '/uploads'; 
  16. else 
  17. $url = trailingslashit( $siteurl ) . $upload_path; 
  18.  
  19. /** 
  20. * Honor the value of UPLOADS. This happens as long as ms-files rewriting is disabled. 
  21. * We also sometimes obey UPLOADS when rewriting is enabled -- see the next block. 
  22. */ 
  23. if ( defined( 'UPLOADS' ) && ! ( is_multisite() && get_site_option( 'ms_files_rewriting' ) ) ) { 
  24. $dir = ABSPATH . UPLOADS
  25. $url = trailingslashit( $siteurl ) . UPLOADS
  26.  
  27. // If multisite (and if not the main site in a post-MU network) 
  28. if ( is_multisite() && ! ( is_main_network() && is_main_site() && defined( 'MULTISITE' ) ) ) { 
  29.  
  30. if ( ! get_site_option( 'ms_files_rewriting' ) ) { 
  31. /** 
  32. * If ms-files rewriting is disabled (networks created post-3.5), it is fairly 
  33. * straightforward: Append sites/%d if we're not on the main site (for post-MU 
  34. * networks). (The extra directory prevents a four-digit ID from conflicting with 
  35. * a year-based directory for the main site. But if a MU-era network has disabled 
  36. * ms-files rewriting manually, they don't need the extra directory, as they never 
  37. * had wp-content/uploads for the main site.) 
  38. */ 
  39.  
  40. if ( defined( 'MULTISITE' ) ) 
  41. $ms_dir = '/sites/' . get_current_blog_id(); 
  42. else 
  43. $ms_dir = '/' . get_current_blog_id(); 
  44.  
  45. $dir .= $ms_dir; 
  46. $url .= $ms_dir; 
  47.  
  48. } elseif ( defined( 'UPLOADS' ) && ! ms_is_switched() ) { 
  49. /** 
  50. * Handle the old-form ms-files.php rewriting if the network still has that enabled. 
  51. * When ms-files rewriting is enabled, then we only listen to UPLOADS when: 
  52. * 1) We are not on the main site in a post-MU network, as wp-content/uploads is used 
  53. * there, and 
  54. * 2) We are not switched, as ms_upload_constants() hardcodes these constants to reflect 
  55. * the original blog ID. 
  56. * Rather than UPLOADS, we actually use BLOGUPLOADDIR if it is set, as it is absolute. 
  57. * (And it will be set, see ms_upload_constants().) Otherwise, UPLOADS can be used, as 
  58. * as it is relative to ABSPATH. For the final piece: when UPLOADS is used with ms-files 
  59. * rewriting in multisite, the resulting URL is /files. (#WP22702 for background.) 
  60. */ 
  61.  
  62. if ( defined( 'BLOGUPLOADDIR' ) ) 
  63. else 
  64. $dir = ABSPATH . UPLOADS
  65. $url = trailingslashit( $siteurl ) . 'files'; 
  66.  
  67. $basedir = $dir; 
  68. $baseurl = $url; 
  69.  
  70. $subdir = ''; 
  71. if ( get_option( 'uploads_use_yearmonth_folders' ) ) { 
  72. // Generate the yearly and monthly dirs 
  73. if ( !$time ) 
  74. $time = current_time( 'mysql' ); 
  75. $y = substr( $time, 0, 4 ); 
  76. $m = substr( $time, 5, 2 ); 
  77. $subdir = "/$y/$m"; 
  78.  
  79. $dir .= $subdir; 
  80. $url .= $subdir; 
  81.  
  82. return array( 
  83. 'path' => $dir,  
  84. 'url' => $url,  
  85. 'subdir' => $subdir,  
  86. 'basedir' => $basedir,  
  87. 'baseurl' => $baseurl,  
  88. error => false,  
  89. );