wp_upload_dir( string|null $time = null, bool $create_dir = true, bool $refresh_cache = false ): array

Description

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.

• $pathstring

  Base directory and subdirectory or full path to upload directory.

• $urlstring

  Base URL and subdirectory or absolute URL to upload directory.

• $subdirstring

  Subdirectory if uploads use year/month folders option is on.

• $basedirstring

  Path without subdir.

• $baseurlstring

  URL path without subdir.

• $errorstring|false

  False or error message.

Hooks fired · 1

One hook fires while wp_upload_dir() runs, in this order:

1. 1
   apply_filters( upload_dir )filterline 2406 (+25 into the body)

   Filters the uploads directory data.

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.

Source

View on Trac ↗View on GitHub ↗

2381function wp_upload_dir( $time = null, $create_dir = true, $refresh_cache = false ) {2382	static $cache = array(), $tested_paths = array();2383 2384	$key = sprintf( '%d-%s', get_current_blog_id(), (string) $time );2385 2386	if ( $refresh_cache || empty( $cache[ $key ] ) ) {2387		$cache[ $key ] = _wp_upload_dir( $time );2388	}2389 2390	/**2391	 * Filters the uploads directory data.2392	 *2393	 * @since 2.0.02394	 *2395	 * @param array $uploads {2396	 *     Array of information about the upload directory.2397	 *2398	 *     @type string       $path    Base directory and subdirectory or full path to upload directory.2399	 *     @type string       $url     Base URL and subdirectory or absolute URL to upload directory.2400	 *     @type string       $subdir  Subdirectory if uploads use year/month folders option is on.2401	 *     @type string       $basedir Path without subdir.2402	 *     @type string       $baseurl URL path without subdir.2403	 *     @type string|false $error   False or error message.2404	 * }2405	 */2406	$uploads = apply_filters( 'upload_dir', $cache[ $key ] );2407 2408	if ( $create_dir ) {2409		$path = $uploads['path'];2410 2411		if ( array_key_exists( $path, $tested_paths ) ) {2412			$uploads['error'] = $tested_paths[ $path ];2413		} else {2414			if ( ! wp_mkdir_p( $path ) ) {2415				if ( str_starts_with( $uploads['basedir'], ABSPATH ) ) {2416					$error_path = str_replace( ABSPATH, '', $uploads['basedir'] ) . $uploads['subdir'];2417				} else {2418					$error_path = wp_basename( $uploads['basedir'] ) . $uploads['subdir'];2419				}2420 2421				$uploads['error'] = sprintf(2422					/* translators: %s: Directory path. */2423					__( 'Unable to create directory %s. Is its parent directory writable by the server?' ),2424					esc_html( $error_path )2425				);2426			}2427 2428			$tested_paths[ $path ] = $uploads['error'];2429		}2430	}2431 2432	return $uploads;2433}

History

Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 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.