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
Returns an array containing the current upload directory's path and URL.
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.
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
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.
Hooks 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
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;}History
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.