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 8817 (+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 ↗

8763function recurse_dirsize( $directory, $exclude = null, $max_execution_time = null, &$directory_cache = null ) {8764	$directory  = untrailingslashit( $directory );8765	$save_cache = false;8766 8767	if ( ! isset( $directory_cache ) ) {8768		$directory_cache = get_transient( 'dirsize_cache' );8769		$save_cache      = true;8770	}8771 8772	if ( isset( $directory_cache[ $directory ] ) && is_int( $directory_cache[ $directory ] ) ) {8773		return $directory_cache[ $directory ];8774	}8775 8776	if ( ! file_exists( $directory ) || ! is_dir( $directory ) || ! is_readable( $directory ) ) {8777		return false;8778	}8779 8780	if (8781		( is_string( $exclude ) && $directory === $exclude ) ||8782		( is_array( $exclude ) && in_array( $directory, $exclude, true ) )8783	) {8784		return false;8785	}8786 8787	if ( null === $max_execution_time ) {8788		// Keep the previous behavior but attempt to prevent fatal errors from timeout if possible.8789		if ( function_exists( 'ini_get' ) ) {8790			$max_execution_time = ini_get( 'max_execution_time' );8791		} else {8792			// Disable...8793			$max_execution_time = 0;8794		}8795 8796		// Leave 1 second "buffer" for other operations if $max_execution_time has reasonable value.8797		if ( $max_execution_time > 10 ) {8798			$max_execution_time -= 1;8799		}8800	}8801 8802	/**8803	 * Filters the amount of storage space used by one directory and all its children, in megabytes.8804	 *8805	 * Return the actual used space to short-circuit the recursive PHP file size calculation8806	 * and use something else, like a CDN API or native operating system tools for better performance.8807	 *8808	 * @since 5.6.08809	 *8810	 * @param int|false            $space_used         The amount of used space, in bytes. Default false.8811	 * @param string               $directory          Full path of a directory.8812	 * @param string|string[]|null $exclude            Full path of a subdirectory to exclude from the total,8813	 *                                                 or array of paths.8814	 * @param int                  $max_execution_time Maximum time to run before giving up. In seconds.8815	 * @param array                $directory_cache    Array of cached directory paths.8816	 */8817	$size = apply_filters( 'pre_recurse_dirsize', false, $directory, $exclude, $max_execution_time, $directory_cache );8818 8819	if ( false === $size ) {8820		$size = 0;8821 8822		$handle = opendir( $directory );8823		if ( $handle ) {8824			while ( ( $file = readdir( $handle ) ) !== false ) {8825				$path = $directory . '/' . $file;8826				if ( '.' !== $file && '..' !== $file ) {8827					if ( is_file( $path ) ) {8828						$size += filesize( $path );8829					} elseif ( is_dir( $path ) ) {8830						$handlesize = recurse_dirsize( $path, $exclude, $max_execution_time, $directory_cache );8831						if ( $handlesize > 0 ) {8832							$size += $handlesize;8833						}8834					}8835 8836					if ( $max_execution_time > 0 &&8837						( microtime( true ) - WP_START_TIMESTAMP ) > $max_execution_time8838					) {8839						// Time exceeded. Give up instead of risking a fatal timeout.8840						$size = null;8841						break;8842					}

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.9.7 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.