From 025ad3469b50efab48cb21e2b124ea2bc2362b50 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Tue, 17 Nov 2020 15:36:02 +0000 Subject: [PATCH] Docs: Adjust comments for `recurse_dirsize()` and related tests per the documentation standards. Follow-up to [49212], [49616]. See #19879. git-svn-id: https://develop.svn.wordpress.org/trunk@49628 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/functions.php | 33 ++- .../tests/multisite/cleanDirsizeCache.php | 244 ++++++++++-------- 2 files changed, 147 insertions(+), 130 deletions(-) diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php index ccf89a449d..81ed9bc130 100644 --- a/src/wp-includes/functions.php +++ b/src/wp-includes/functions.php @@ -7607,13 +7607,12 @@ function get_dirsize( $directory, $max_execution_time = null ) { /** * Get the size of a directory recursively. * - * Used by get_dirsize() to get a directory's size when it contains - * other directories. + * Used by get_dirsize() to get a directory size when it contains other directories. * * @since MU (3.0.0) - * @since 4.3.0 $exclude parameter added. - * @since 5.2.0 $max_execution_time parameter added. - * @since 5.6.0 $directory_cache parameter added. + * @since 4.3.0 The `$exclude` parameter was added. + * @since 5.2.0 The `$max_execution_time` parameter was added. + * @since 5.6.0 The `$directory_cache` parameter was added. * * @param string $directory Full path of a directory. * @param string|array $exclude Optional. Full path of a subdirectory to exclude from the total, @@ -7668,14 +7667,15 @@ function recurse_dirsize( $directory, $exclude = null, $max_execution_time = nul } /** - * Filters the amount of storage space used by one directory and all it's children, in megabytes. - * Return the actual used space to shortcircuit the recursive PHP file size calculation and use something else - * like a CDN API or native operating system tools for better performance - * - * @since 5.6.0 - * - * @param int|false $space_used The amount of used space, in bytes. Default 0. - */ + * Filters the amount of storage space used by one directory and all its children, in megabytes. + * + * Return the actual used space to short-circuit the recursive PHP file size calculation + * and use something else, like a CDN API or native operating system tools for better performance. + * + * @since 5.6.0 + * + * @param int|false $space_used The amount of used space, in bytes. Default 0. + */ $size = apply_filters( 'calculate_current_dirsize', $size, $directory, $exclude, $max_execution_time, $directory_cache ); if ( 0 === $size ) { @@ -7705,7 +7705,7 @@ function recurse_dirsize( $directory, $exclude = null, $max_execution_time = nul } $directory_cache[ $cache_path ] = $size; - // Only write the transient on the top level call and not on recursive calls + // Only write the transient on the top level call and not on recursive calls. if ( $save_cache ) { set_transient( 'dirsize_cache', $directory_cache ); } @@ -7714,10 +7714,9 @@ function recurse_dirsize( $directory, $exclude = null, $max_execution_time = nul } /** - * Invalidates entries within the dirsize_cache + * Cleans directory size cache used by recurse_dirsize(). * - * Remove the current directory and all parent directories - * from the dirsize_cache transient. + * Removes the current directory and all parent directories from the `dirsize_cache` transient. * * @since 5.6.0 * diff --git a/tests/phpunit/tests/multisite/cleanDirsizeCache.php b/tests/phpunit/tests/multisite/cleanDirsizeCache.php index 816eba4393..e30f50a3bc 100644 --- a/tests/phpunit/tests/multisite/cleanDirsizeCache.php +++ b/tests/phpunit/tests/multisite/cleanDirsizeCache.php @@ -3,8 +3,9 @@ if ( is_multisite() ) : /** - * Tests specific to the dirsize caching in multisites + * Tests specific to the directory size caching in multisite. * + * @ticket 19879 * @group multisite */ class Tests_Multisite_Dirsize_Cache extends WP_UnitTestCase { @@ -22,31 +23,35 @@ if ( is_multisite() ) : parent::tearDown(); } - /* - * Test whether the values from the dirsize_cache will be used correctly using a more complex dirsize cache mock + /** + * Test whether dirsize_cache values are used correctly with a more complex dirsize cache mock. + * + * @ticket 19879 */ function test_get_dirsize_cache_in_recurse_dirsize_mock() { $blog_id = self::factory()->blog->create(); switch_to_blog( $blog_id ); - // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the - // src directory already contains a content directory with site content, then the initial expectation - // will be polluted. We create sites until an empty one is available. + /* + * Our comparison of space relies on an initial value of 0. If a previous test has failed + * or if the `src` directory already contains a content directory with site content, then + * the initial expectation will be polluted. We create sites until an empty one is available. + */ while ( 0 !== get_space_used() ) { restore_current_blog(); $blog_id = self::factory()->blog->create(); switch_to_blog( $blog_id ); } - // Clear the dirsize_cache + // Clear the dirsize cache. delete_transient( 'dirsize_cache' ); - // Set the dirsize cache to our mock + // Set the dirsize cache to our mock. set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) ); $upload_dir = wp_upload_dir(); - // Check recurse_dirsize against the mock. The cache should match + // Check recurse_dirsize() against the mock. The cache should match. $this->assertSame( 21, recurse_dirsize( $upload_dir['basedir'] . '/2/1' ) ); $this->assertSame( 22, recurse_dirsize( $upload_dir['basedir'] . '/2/2' ) ); $this->assertSame( 2, recurse_dirsize( $upload_dir['basedir'] . '/2' ) ); @@ -56,131 +61,141 @@ if ( is_multisite() ) : $this->assertSame( 1, recurse_dirsize( $upload_dir['basedir'] . '/1' ) ); $this->assertSame( 42, recurse_dirsize( $upload_dir['basedir'] . '/custom_directory' ) ); - // No cache match, upload folder should be empty and return 0 + // No cache match, upload directory should be empty and return 0. $this->assertSame( 0, recurse_dirsize( $upload_dir['basedir'] ) ); - // No cache match on non existing folder should return false + // No cache match on non existing directory should return false. $this->assertSame( false, recurse_dirsize( $upload_dir['basedir'] . '/does_not_exist' ) ); - // Cleanup - $this->remove_added_uploads(); - restore_current_blog(); - } - - /* - * Test whether the invalidation of the dirsize_cache works - * Given a file path as input - */ - function test_clean_dirsize_cache_file_input_mock() { - $blog_id = self::factory()->blog->create(); - switch_to_blog( $blog_id ); - - // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the - // src directory already contains a content directory with site content, then the initial expectation - // will be polluted. We create sites until an empty one is available. - while ( 0 !== get_space_used() ) { - restore_current_blog(); - $blog_id = self::factory()->blog->create(); - switch_to_blog( $blog_id ); - } - - $upload_dir = wp_upload_dir(); - $cache_key_prefix = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['basedir'] ) ); - - // Clear the dirsize_cache - delete_transient( 'dirsize_cache' ); - - // Set the dirsize cache to our mock - set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) ); - - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); - - // Invalidation should also respect the directory tree up - // Should work fine with path to folder OR file - clean_dirsize_cache( $upload_dir['basedir'] . '/2/1/file.dummy' ); - - $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); - $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); - - // Other cache paths should not be invalidated - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); - - // Cleanup - $this->remove_added_uploads(); - restore_current_blog(); - } - - /* - * Test whether the invalidation of the dirsize_cache works - * Given a folder path as input - */ - function test_clean_dirsize_cache_folder_input_mock() { - $blog_id = self::factory()->blog->create(); - switch_to_blog( $blog_id ); - - // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the - // src directory already contains a content directory with site content, then the initial expectation - // will be polluted. We create sites until an empty one is available. - while ( 0 !== get_space_used() ) { - restore_current_blog(); - $blog_id = self::factory()->blog->create(); - switch_to_blog( $blog_id ); - } - - $upload_dir = wp_upload_dir(); - $cache_key_prefix = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['basedir'] ) ); - - // Clear the dirsize_cache - delete_transient( 'dirsize_cache' ); - - // Set the dirsize cache to our mock - set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) ); - - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); - - // Invalidation should also respect the directory tree up - // Should work fine with path to folder OR file - clean_dirsize_cache( $upload_dir['basedir'] . '/2/1' ); - - $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); - $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); - - // Other cache paths should not be invalidated - $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); - - // Cleanup + // Cleanup. $this->remove_added_uploads(); restore_current_blog(); } /** - * Test whether the values from the dirsize_cache will be used correctly using a simple real upload + * Test whether the dirsize_cache invalidation works given a file path as input. + * + * @ticket 19879 */ - function test_get_dirsize_cache_in_recurse_dirsize_upload() { + function test_clean_dirsize_cache_file_input_mock() { $blog_id = self::factory()->blog->create(); switch_to_blog( $blog_id ); - // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the - // src directory already contains a content directory with site content, then the initial expectation - // will be polluted. We create sites until an empty one is available. + /* + * Our comparison of space relies on an initial value of 0. If a previous test has failed + * or if the `src` directory already contains a content directory with site content, then + * the initial expectation will be polluted. We create sites until an empty one is available. + */ while ( 0 !== get_space_used() ) { restore_current_blog(); $blog_id = self::factory()->blog->create(); switch_to_blog( $blog_id ); } - // Clear the dirsize_cache + $upload_dir = wp_upload_dir(); + $cache_key_prefix = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['basedir'] ) ); + + // Clear the dirsize cache. + delete_transient( 'dirsize_cache' ); + + // Set the dirsize cache to our mock. + set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) ); + + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); + + // Invalidation should also respect the directory tree up. + // Should work fine with path to directory OR file. + clean_dirsize_cache( $upload_dir['basedir'] . '/2/1/file.dummy' ); + + $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); + $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); + + // Other cache paths should not be invalidated. + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); + + // Cleanup. + $this->remove_added_uploads(); + restore_current_blog(); + } + + /** + * Test whether the dirsize_cache invalidation works given a directory path as input. + * + * @ticket 19879 + */ + function test_clean_dirsize_cache_folder_input_mock() { + $blog_id = self::factory()->blog->create(); + switch_to_blog( $blog_id ); + + /* + * Our comparison of space relies on an initial value of 0. If a previous test has failed + * or if the `src` directory already contains a content directory with site content, then + * the initial expectation will be polluted. We create sites until an empty one is available. + */ + while ( 0 !== get_space_used() ) { + restore_current_blog(); + $blog_id = self::factory()->blog->create(); + switch_to_blog( $blog_id ); + } + + $upload_dir = wp_upload_dir(); + $cache_key_prefix = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['basedir'] ) ); + + // Clear the dirsize cache. + delete_transient( 'dirsize_cache' ); + + // Set the dirsize cache to our mock. + set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) ); + + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); + + // Invalidation should also respect the directory tree up. + // Should work fine with path to directory OR file. + clean_dirsize_cache( $upload_dir['basedir'] . '/2/1' ); + + $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2/1', get_transient( 'dirsize_cache' ) ) ); + $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) ); + + // Other cache paths should not be invalidated. + $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) ); + + // Cleanup. + $this->remove_added_uploads(); + restore_current_blog(); + } + + /** + * Test whether dirsize_cache values are used correctly with a simple real upload. + * + * @ticket 19879 + */ + function test_get_dirsize_cache_in_recurse_dirsize_upload() { + $blog_id = self::factory()->blog->create(); + switch_to_blog( $blog_id ); + + /* + * Our comparison of space relies on an initial value of 0. If a previous test has failed + * or if the `src` directory already contains a content directory with site content, then + * the initial expectation will be polluted. We create sites until an empty one is available. + */ + while ( 0 !== get_space_used() ) { + restore_current_blog(); + $blog_id = self::factory()->blog->create(); + switch_to_blog( $blog_id ); + } + + // Clear the dirsize cache. delete_transient( 'dirsize_cache' ); $upload_dir = wp_upload_dir(); $this->assertSame( 0, recurse_dirsize( $upload_dir['path'] ) ); - // Upload a file to the new site using wp_upload_bits. + // Upload a file to the new site using wp_upload_bits(). $filename = __FUNCTION__ . '.jpg'; $contents = __FUNCTION__ . '_contents'; $file = wp_upload_bits( $filename, null, $contents ); @@ -189,18 +204,20 @@ if ( is_multisite() ) : $size = filesize( $file['file'] ); $this->assertSame( $size, $calc_size ); - // dirsize_cache should now be filled after upload and recurse_dirsize call + // `dirsize_cache` should now be filled after upload and recurse_dirsize() call. $cache_path = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['path'] ) ); $this->assertSame( true, is_array( get_transient( 'dirsize_cache' ) ) ); $this->assertSame( $size, get_transient( 'dirsize_cache' )[ $cache_path ] ); - // Cleanup + // Cleanup. $this->remove_added_uploads(); restore_current_blog(); } - /* - * Test whether the filter to calculate space for an existing directory works as expected + /** + * Test whether the filter to calculate space for an existing directory works as expected. + * + * @ticket 19879 */ function test_recurse_dirsize_calculate_current_dirsize_filter() { add_filter( 'calculate_current_dirsize', array( $this, '_filter_calculate_current_dirsize' ) ); @@ -228,4 +245,5 @@ if ( is_multisite() ) : ); } } + endif;