recurse_dirsize( string $directory, string|string[] $exclude = null, int $max_execution_time = null, array $directory_cache = null ): int|false|null

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$directorystring

Full path of a directory.

$excludestring|string[]optional

Full path of a subdirectory to exclude from the total, or array of paths. Expected without trailing slash(es).
Default null.Default: null

$max_execution_timeintoptional

Maximum time to run before giving up. In seconds.
The timeout is global and is measured from the moment WordPress started to load. Defaults to the value of max_execution_time PHP setting.Default: null

$directory_cachearrayoptional

Array of cached directory paths.
Defaults to the value of dirsize_cache transient.Default: null

Return value

int|false|null

Size in bytes if a valid directory. False if not. Null if timeout.

Performance profile

How much work a call to recurse_dirsize() 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

Heavy

Reads or writes the filesystem via file_exists().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

18–132

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 143.

Plugin surface

1 hook

Third-party callbacks on 'pre_recurse_dirsize' run inside this call, and their cost is not bounded by anything here.

Called by

3

3 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• transienttransientget_transient()called directly
• hookthird-party callbacksapply_filters()called directly
• filesystemfilesystem accessfile_exists()called directly
• cacheobject cachewp_cache_get()one call below recurse_dirsize()
• optionoption read or writeget_option()one call below recurse_dirsize()

Further down the call graph this can also reach serialize and query. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 56 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost recurse_dirsize() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 1

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

1. 1
   apply_filters( pre_recurse_dirsize )filterline 8765 (+54 into the body)

   Filters the amount of storage space used by one directory and all its children, in megabytes.

Uses · 6

• untrailingslashit()Removes trailing forward slashes and backslashes if they exist.
• get_transient()Retrieves the value of a transient.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• recurse_dirsize()Gets the size of a directory recursively.
• wp_using_ext_object_cache()Toggles `$_wp_using_ext_object_cache` on and off without directly touching global.
• set_transient()Sets/updates the value of a transient.

Used by · 3

• WP_Debug_Data::get_sizes()Fetches the sizes of the WordPress directories: `wordpress` (ABSPATH), `plugins`, `themes`, and `uploads`.
• get_dirsize()Gets the size of a directory.
• recurse_dirsize()Gets the size of a directory recursively.

Source code

View on Trac ↗View on GitHub ↗

8711function recurse_dirsize( $directory, $exclude = null, $max_execution_time = null, &$directory_cache = null ) {8712	$directory  = untrailingslashit( $directory );8713	$save_cache = false;8714 8715	if ( ! isset( $directory_cache ) ) {8716		$directory_cache = get_transient( 'dirsize_cache' );8717		$save_cache      = true;8718	}8719 8720	if ( isset( $directory_cache[ $directory ] ) && is_int( $directory_cache[ $directory ] ) ) {8721		return $directory_cache[ $directory ];8722	}8723 8724	if ( ! file_exists( $directory ) || ! is_dir( $directory ) || ! is_readable( $directory ) ) {8725		return false;8726	}8727 8728	if (8729		( is_string( $exclude ) && $directory === $exclude ) ||8730		( is_array( $exclude ) && in_array( $directory, $exclude, true ) )8731	) {8732		return false;8733	}8734 8735	if ( null === $max_execution_time ) {8736		// Keep the previous behavior but attempt to prevent fatal errors from timeout if possible.8737		if ( function_exists( 'ini_get' ) ) {8738			$max_execution_time = ini_get( 'max_execution_time' );8739		} else {8740			// Disable...8741			$max_execution_time = 0;8742		}8743 8744		// Leave 1 second "buffer" for other operations if $max_execution_time has reasonable value.8745		if ( $max_execution_time > 10 ) {8746			$max_execution_time -= 1;8747		}8748	}8749 8750	/**8751	 * Filters the amount of storage space used by one directory and all its children, in megabytes.8752	 *8753	 * Return the actual used space to short-circuit the recursive PHP file size calculation8754	 * and use something else, like a CDN API or native operating system tools for better performance.8755	 *8756	 * @since 5.6.08757	 *8758	 * @param int|false            $space_used         The amount of used space, in bytes. Default false.8759	 * @param string               $directory          Full path of a directory.8760	 * @param string|string[]|null $exclude            Full path of a subdirectory to exclude from the total,8761	 *                                                 or array of paths.8762	 * @param int                  $max_execution_time Maximum time to run before giving up. In seconds.8763	 * @param array                $directory_cache    Array of cached directory paths.8764	 */8765	$size = apply_filters( 'pre_recurse_dirsize', false, $directory, $exclude, $max_execution_time, $directory_cache );8766 8767	if ( false === $size ) {8768		$size = 0;8769 8770		$handle = opendir( $directory );8771		if ( $handle ) {8772			while ( ( $file = readdir( $handle ) ) !== false ) {8773				$path = $directory . '/' . $file;8774				if ( '.' !== $file && '..' !== $file ) {8775					if ( is_file( $path ) ) {8776						$size += filesize( $path );8777					} elseif ( is_dir( $path ) ) {8778						$handlesize = recurse_dirsize( $path, $exclude, $max_execution_time, $directory_cache );8779						if ( $handlesize > 0 ) {8780							$size += $handlesize;8781						}8782					}8783 8784					if ( $max_execution_time > 0 &&8785						( microtime( true ) - WP_START_TIMESTAMP ) > $max_execution_time8786					) {8787						// Time exceeded. Give up instead of risking a fatal timeout.8788						$size = null;8789						break;8790					}

Changelog

Introduced in 5.6.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 6.8.8 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.