wp_upload_dir() │ WP 2.0.0

Gets upload directory data: path, URL.

The uploads folder is usually named uploads and is located in the wp-contents content folder.

Checks the upload_path option, which should be a path from the site root and if the option is set, it will be used, and if not set, then the path will be: WP_CONTENT_DIR/uploads. However, if the UPLOADS constant is defined, then it will override the upload_path option and the WP_CONTENT_DIR/uploads path.

The URL of the upload directory is set via the upload_url_path option or the WP_CONTENT_URL/uploads construct is used.

If the uploads_use_yearmonth_folders option is set (checkbox in the Media Settings in the admin panel), then the current year and month will be added to the paths and links, in the format /YYYY/MM.

If WordPress cannot determine the path, then the error element of the array will contain an error message. An error can occur when the parent directory forbids creating children (not enough write permissions).

A faster alternative to this function: wp_get_upload_dir().

Multisite

For Multisite the function will return the upload folder data of the current site. For example:

[basedir] => /var/app/www/wp-content/uploads/sites/2
[baseurl] => https://example.com/wp-content/uploads/sites/2

Notes

#1 The function creates folders

When used the function wp_upload_dir() creates a subdirectory if it does not exist. If the $time parameter is specified, the specified subdirectory will be created, otherwise the current month directory. It is not necessary to save a file for the directory to be created.

#2 Folder name

If you need to move the uploads folder /uploads, you need to define the UPLOADS constant in the wp-config.php file. For example:

define( 'UPLOADS', trailingslashit( WP_CONTENT_DIR ) . 'custom_uploads_name' );

#3 Uploads folder name

To get the name of the uploads folder relative to the content directory, you can usually use this construct. It is assumed here that the uploads directory is located in the content directory:

$upload_dir_name = false;
if ( defined( 'UPLOADS' ) ) {
	$upload_dir_name = = str_replace( trailingslashit( WP_CONTENT_DIR ), '', untrailingslashit( UPLOADS ) );
}

IMPORTANT: the UPLOADS constant is not defined by default in WP. It can be defined only for Multisite and only if the ms_files_rewriting=1 option is set, but usually the value of this option is 0 and the UPLOADS constant is not defined. For more details see the code of the function ms_upload_constants().

Uses: _wp_upload_dir()

Used By: wp_font_dir(), wp_get_upload_dir(), wp_upload_bits()

1 time — 0.000233 sec (fast) | 50000 times — 0.23 sec (very fast) | PHP 7.0.5, WP 4.5

Hooks from the function

upload_dir

Returns

Array. An array of upload directory data:

array (
  'path'    => '/home/example.com/public_html/wp-content/uploads/2016/04',
  'url'     => 'http://example.com/wp-content/uploads/2016/04',
  'subdir'  => '/2016/04',
  'basedir' => '/home/example.com/public_html/wp-content/uploads',
  'baseurl' => 'http://example.com/wp-content/uploads',
  'error'   => false,
)

where:

path - server path to the uploads directory taking into account the year and month, if the corresponding option is enabled in the admin.
url - URL of the uploads directory taking into account the year and month, if the corresponding option is enabled in the admin.
subdir - the name of the final uploads directory inside wp-content/uploads.
basedir - server path to the main uploads directory.
baseurl - URL to the main uploads directory.
error - in case of an error when getting data the error element of the array will be true.

Usage

wp_upload_dir( $time, $create_dir, $refresh_cache );

$time(string): Subdirectory of the uploads directory. Usually these are folders /YYYY/MM in the uploads directory. Here we can specify any subdirectory in the format /YYYY/MM, the returned array data depend on this parameter: [path] [url] [subdir].
Default: null (current month folder)
$create_dir(boolean): Should the uploads directory be checked and created if it does not exist?
Default: true
$refresh_cache(boolean): Should the cache be refreshed? The function result is cached and returned from cache. If set to true here, the cache will be recreated.
Default: false

Examples

#1 What the array returns

$upload_dir = wp_upload_dir();
print_r( $upload_dir );

// will return:
/*
Array
(
	[path] => /home/k/wp-example.com/public_html/wp-content/uploads/2014/02
	[url] => http://wp-example.com/wp-content/uploads/2014/02
	[subdir] => /2014/02
	[basedir] => /home/k/wp-example.com/public_html/wp-content/uploads
	[baseurl] => http://wp-example.com/wp-content/uploads
	[error] =>
)
*/

#2 The URL of the WordPress download directory

Get the URL of the WordPress downloads directory:

$upload_dir = wp_upload_dir();
echo $upload_dir['baseurl']; //> http://wp-example.com/wp-content/uploads

-1

#3 Getting all elements as an object

It is more convenient to get elements in the form of an object, so it is convenient to work with them:

$upload_dir = (object) wp_upload_dir();

if( ! $upload_dir->error ){
	echo $upload_dir->path ."\n";
	echo $upload_dir->url ."\n";
	echo $upload_dir->subdir ."\n";
	echo $upload_dir->basedir ."\n";
	echo $upload_dir->baseurl ."\n";
}

/* we get:
/home/wp-example.com/public_html/wp-content/uploads/2015/08
http://wp-example.com/wp-content/uploads/2015/08
/2015/08
/home/wp-example.com/public_html/wp-content/uploads
http://wp-example.com/wp-content/uploads
*/

Changelog

Since 2.0.0

Introduced.

`wp_upload_dir() wp upload dir` code ^{WP 7.0}

wp-includes/functions.php

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;
}