wp_upload_dir( string|null $time = null, bool $create_dir = true, bool $refresh_cache = false ): array
- Since
- 2.0.0
- Source
wp-includes/functions.php:2404
Description
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.
Compatibility
- WordPress
- since 2.0.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$timestring|nulloptional- Time formatted in 'yyyy/mm'. Default null.Default:
null $create_dirbooloptional- Whether to check and create the uploads directory.
Default true for backward compatibility.Default:true $refresh_cachebooloptional- Whether to refresh the cache. Default false.Default:
false
Return value
array- Array of information about the upload directory.
$pathstringBase directory and subdirectory or full path to upload directory.$urlstringBase URL and subdirectory or absolute URL to upload directory.$subdirstringSubdirectory if uploads use year/month folders option is on.$basedirstringPath without subdir.$baseurlstringURL path without subdir.$errorstring|falseFalse or error message.
Performance profile
How much work a call to wp_upload_dir() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Moderate
- Scaling
- Constant
- Instructions
- 24–62
- Plugin surface
- 1 hook
- Called by
- 14
Reads stored settings via get_option(), cached per request but not free on a cold cache.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 73.
Third-party callbacks on 'upload_dir' run inside this call, and their cost is not bounded by anything here.
14 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly - optionoption read or write
get_option()one call below wp_upload_dir()
Further down the call graph this can also reach cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 8 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_upload_dir() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
!empty($cache[$key]) | 24–30 | get_current_blog_id(), apply_filters() |
| always | 27–35 | get_current_blog_id(), _wp_upload_dir(), apply_filters() |
!empty($cache[$key]) && !$path && wp_mkdir_p() | 34 | get_current_blog_id(), apply_filters(), wp_mkdir_p() |
!$path && wp_mkdir_p() | 37–39 | get_current_blog_id(), _wp_upload_dir(), apply_filters(), wp_mkdir_p() |
!empty($cache[$key]) && !$path && !wp_mkdir_p() | 57 | get_current_blog_id(), apply_filters(), wp_mkdir_p(), __(), esc_html(), sprintf() |
!empty($cache[$key]) && !$path && !wp_mkdir_p() | 57 | get_current_blog_id(), apply_filters(), wp_mkdir_p(), wp_basename(), __(), esc_html(), sprintf() |
!$path && !wp_mkdir_p() | 60–62 | get_current_blog_id(), _wp_upload_dir(), apply_filters(), wp_mkdir_p(), __(), esc_html(), sprintf() |
!$path && !wp_mkdir_p() | 60–62 | get_current_blog_id(), _wp_upload_dir(), apply_filters(), wp_mkdir_p(), wp_basename(), __(), esc_html(), sprintf() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 73 | 24–62 | 6 | |
| 8.5 | 73 | 24–62 | 6 | |
| 8.4 | 73 | 24–62 | 6 | 8 fewer instructions than PHP 8.3 |
| 8.3 | 81 | 26–70 | 6 | |
| 8.2 | 81 | 26–70 | 6 | |
| 8.1 | 81 | 26–70 | 6 | 1 fewer instruction than PHP 7.4 |
| 7.4 | 82 | 26–71 | 6 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 1
One hook fires while wp_upload_dir() runs, in this order:
Uses · 8
- get_current_blog_id()Retrieves the current site ID.
- _wp_upload_dir()A non-filtered, non-cached version of wp_upload_dir() that doesn't check the path.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- wp_mkdir_p()Recursive directory creation based on full path.
- str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
- wp_basename()i18n-friendly version of basename().
- __()Retrieves the translation of $text.
- esc_html()Escaping for HTML blocks.
Used by · 14
- File_Upload_Upgrader::__construct()Construct the upgrader for a form.
- WP_Debug_Data::get_wp_filesystem()Gets the file system section of the debug data.
- WP_Debug_Data::get_wp_paths_sizes()Gets the WordPress paths and sizes section of the debug data.
- WP_REST_Attachments_Controller::edit_media_item()Applies edits to a media item and creates a new attachment record.
- WP_URL_Pattern_Prefixer::get_default_contexts()Returns the default contexts used by the class.
- _wp_handle_upload()Handles PHP uploads in WordPress.
- _wp_kses_allow_pdf_objects()Helper function to check if this is a safe PDF URL.
- get_space_used()Returns the space used by the current site.
- wp_font_dir()Returns an array containing the current fonts upload directory's path and URL.
- wp_get_upload_dir()Retrieves uploads directory information.
- wp_import_upload_form()Outputs the form used by the importers to accept the data to be imported.
- wp_privacy_exports_dir()Returns the directory used to store personal data export files.
Show all 14
- wp_privacy_exports_url()Returns the URL of the directory used to store personal data export files.
- wp_upload_bits()Creates a file in the upload folder with given content.
Source code
function wp_upload_dir( $time = null, $create_dir = true, $refresh_cache = false ) { static $cache = array(), $tested_paths = array(); $key = sprintf( '%d-%s', get_current_blog_id(), (string) $time ); if ( $refresh_cache || empty( $cache[ $key ] ) ) { $cache[ $key ] = _wp_upload_dir( $time ); } /** * Filters the uploads directory data. * * @since 2.0.0 * * @param array $uploads { * Array of information about the upload directory. * * @type string $path Base directory and subdirectory or full path to upload directory. * @type string $url Base URL and subdirectory or absolute URL to upload directory. * @type string $subdir Subdirectory if uploads use year/month folders option is on. * @type string $basedir Path without subdir. * @type string $baseurl URL path without subdir. * @type string|false $error False or error message. * } */ $uploads = apply_filters( 'upload_dir', $cache[ $key ] ); if ( $create_dir ) { $path = $uploads['path']; if ( array_key_exists( $path, $tested_paths ) ) { $uploads['error'] = $tested_paths[ $path ]; } else { if ( ! wp_mkdir_p( $path ) ) { if ( str_starts_with( $uploads['basedir'], ABSPATH ) ) { $error_path = str_replace( ABSPATH, '', $uploads['basedir'] ) . $uploads['subdir']; } else { $error_path = wp_basename( $uploads['basedir'] ) . $uploads['subdir']; } $uploads['error'] = sprintf( /* translators: %s: Directory path. */ __( 'Unable to create directory %s. Is its parent directory writable by the server?' ), esc_html( $error_path ) ); } $tested_paths[ $path ] = $uploads['error']; } } return $uploads;}Changelog
Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/functions.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.