Make WordPress Core

Changeset 49628


Ignore:
Timestamp:
11/17/2020 03:36:02 PM (6 years ago)
Author:
SergeyBiryukov
Message:

Docs: Adjust comments for recurse_dirsize() and related tests per the documentation standards.

Follow-up to [49212], [49616].

See #19879.

Location:
trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/functions.php

    r49616 r49628  
    76087608 * Get the size of a directory recursively.
    76097609 *
    7610  * Used by get_dirsize() to get a directory's size when it contains
    7611  * other directories.
     7610 * Used by get_dirsize() to get a directory size when it contains other directories.
    76127611 *
    76137612 * @since MU (3.0.0)
    7614  * @since 4.3.0 $exclude parameter added.
    7615  * @since 5.2.0 $max_execution_time parameter added.
    7616  * @since 5.6.0 $directory_cache parameter added.
     7613 * @since 4.3.0 The `$exclude` parameter was added.
     7614 * @since 5.2.0 The `$max_execution_time` parameter was added.
     7615 * @since 5.6.0 The `$directory_cache` parameter was added.
    76177616 *
    76187617 * @param string       $directory          Full path of a directory.
     
    76697668
    76707669        /**
    7671         * Filters the amount of storage space used by one directory and all it's children, in megabytes.
    7672         * Return the actual used space to shortcircuit the recursive PHP file size calculation and use something else
    7673         * like a CDN API or native operating system tools for better performance
    7674         *
    7675         * @since 5.6.0
    7676         *
    7677         * @param int|false $space_used The amount of used space, in bytes. Default 0.
    7678         */
     7670         * Filters the amount of storage space used by one directory and all its children, in megabytes.
     7671         *
     7672         * Return the actual used space to short-circuit the recursive PHP file size calculation
     7673         * and use something else, like a CDN API or native operating system tools for better performance.
     7674         *
     7675         * @since 5.6.0
     7676         *
     7677         * @param int|false $space_used The amount of used space, in bytes. Default 0.
     7678         */
    76797679        $size = apply_filters( 'calculate_current_dirsize', $size, $directory, $exclude, $max_execution_time, $directory_cache );
    76807680
     
    77067706        $directory_cache[ $cache_path ] = $size;
    77077707
    7708         // Only write the transient on the top level call and not on recursive calls
     7708        // Only write the transient on the top level call and not on recursive calls.
    77097709        if ( $save_cache ) {
    77107710                set_transient( 'dirsize_cache', $directory_cache );
     
    77157715
    77167716/**
    7717  * Invalidates entries within the dirsize_cache
    7718  *
    7719  * Remove the current directory and all parent directories
    7720  * from the dirsize_cache transient.
     7717 * Cleans directory size cache used by recurse_dirsize().
     7718 *
     7719 * Removes the current directory and all parent directories from the `dirsize_cache` transient.
    77217720 *
    77227721 * @since 5.6.0
  • trunk/tests/phpunit/tests/multisite/cleanDirsizeCache.php

    r49616 r49628  
    44
    55        /**
    6          * Tests specific to the dirsize caching in multisites
     6         * Tests specific to the directory size caching in multisite.
    77         *
     8         * @ticket 19879
    89         * @group multisite
    910         */
     
    2324                }
    2425
    25                 /*
    26                  * Test whether the values from the dirsize_cache will be used correctly using a more complex dirsize cache mock
     26                /**
     27                 * Test whether dirsize_cache values are used correctly with a more complex dirsize cache mock.
     28                 *
     29                 * @ticket 19879
    2730                 */
    2831                function test_get_dirsize_cache_in_recurse_dirsize_mock() {
     
    3033                        switch_to_blog( $blog_id );
    3134
    32                         // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the
    33                         // src directory already contains a content directory with site content, then the initial expectation
    34                         // will be polluted. We create sites until an empty one is available.
    35                         while ( 0 !== get_space_used() ) {
    36                                 restore_current_blog();
    37                                 $blog_id = self::factory()->blog->create();
    38                                 switch_to_blog( $blog_id );
    39                         }
    40 
    41                         // Clear the dirsize_cache
    42                         delete_transient( 'dirsize_cache' );
    43 
    44                         // Set the dirsize cache to our mock
     35                        /*
     36                         * Our comparison of space relies on an initial value of 0. If a previous test has failed
     37                         * or if the `src` directory already contains a content directory with site content, then
     38                         * the initial expectation will be polluted. We create sites until an empty one is available.
     39                         */
     40                        while ( 0 !== get_space_used() ) {
     41                                restore_current_blog();
     42                                $blog_id = self::factory()->blog->create();
     43                                switch_to_blog( $blog_id );
     44                        }
     45
     46                        // Clear the dirsize cache.
     47                        delete_transient( 'dirsize_cache' );
     48
     49                        // Set the dirsize cache to our mock.
    4550                        set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) );
    4651
    4752                        $upload_dir = wp_upload_dir();
    4853
    49                         // Check recurse_dirsize against the mock. The cache should match
     54                        // Check recurse_dirsize() against the mock. The cache should match.
    5055                        $this->assertSame( 21, recurse_dirsize( $upload_dir['basedir'] . '/2/1' ) );
    5156                        $this->assertSame( 22, recurse_dirsize( $upload_dir['basedir'] . '/2/2' ) );
     
    5762                        $this->assertSame( 42, recurse_dirsize( $upload_dir['basedir'] . '/custom_directory' ) );
    5863
    59                         // No cache match, upload folder should be empty and return 0
     64                        // No cache match, upload directory should be empty and return 0.
    6065                        $this->assertSame( 0, recurse_dirsize( $upload_dir['basedir'] ) );
    6166
    62                         // No cache match on non existing folder should return false
     67                        // No cache match on non existing directory should return false.
    6368                        $this->assertSame( false, recurse_dirsize( $upload_dir['basedir'] . '/does_not_exist' ) );
    6469
    65                         // Cleanup
    66                         $this->remove_added_uploads();
    67                         restore_current_blog();
    68                 }
    69 
    70                 /*
    71                  * Test whether the invalidation of the dirsize_cache works
    72                  * Given a file path as input
     70                        // Cleanup.
     71                        $this->remove_added_uploads();
     72                        restore_current_blog();
     73                }
     74
     75                /**
     76                 * Test whether the dirsize_cache invalidation works given a file path as input.
     77                 *
     78                 * @ticket 19879
    7379                 */
    7480                function test_clean_dirsize_cache_file_input_mock() {
     
    7682                        switch_to_blog( $blog_id );
    7783
    78                         // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the
    79                         // src directory already contains a content directory with site content, then the initial expectation
    80                         // will be polluted. We create sites until an empty one is available.
     84                        /*
     85                         * Our comparison of space relies on an initial value of 0. If a previous test has failed
     86                         * or if the `src` directory already contains a content directory with site content, then
     87                         * the initial expectation will be polluted. We create sites until an empty one is available.
     88                         */
    8189                        while ( 0 !== get_space_used() ) {
    8290                                restore_current_blog();
     
    8896                        $cache_key_prefix = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['basedir'] ) );
    8997
    90                         // Clear the dirsize_cache
    91                         delete_transient( 'dirsize_cache' );
    92 
    93                         // Set the dirsize cache to our mock
     98                        // Clear the dirsize cache.
     99                        delete_transient( 'dirsize_cache' );
     100
     101                        // Set the dirsize cache to our mock.
    94102                        set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) );
    95103
     
    98106                        $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) );
    99107
    100                         // Invalidation should also respect the directory tree up
    101                         // Should work fine with path to folder OR file
     108                        // Invalidation should also respect the directory tree up.
     109                        // Should work fine with path to directory OR file.
    102110                        clean_dirsize_cache( $upload_dir['basedir'] . '/2/1/file.dummy' );
    103111
     
    105113                        $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) );
    106114
    107                         // Other cache paths should not be invalidated
    108                         $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) );
    109 
    110                         // Cleanup
    111                         $this->remove_added_uploads();
    112                         restore_current_blog();
    113                 }
    114 
    115                 /*
    116                  * Test whether the invalidation of the dirsize_cache works
    117                  * Given a folder path as input
     115                        // Other cache paths should not be invalidated.
     116                        $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) );
     117
     118                        // Cleanup.
     119                        $this->remove_added_uploads();
     120                        restore_current_blog();
     121                }
     122
     123                /**
     124                 * Test whether the dirsize_cache invalidation works given a directory path as input.
     125                 *
     126                 * @ticket 19879
    118127                 */
    119128                function test_clean_dirsize_cache_folder_input_mock() {
     
    121130                        switch_to_blog( $blog_id );
    122131
    123                         // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the
    124                         // src directory already contains a content directory with site content, then the initial expectation
    125                         // will be polluted. We create sites until an empty one is available.
     132                        /*
     133                         * Our comparison of space relies on an initial value of 0. If a previous test has failed
     134                         * or if the `src` directory already contains a content directory with site content, then
     135                         * the initial expectation will be polluted. We create sites until an empty one is available.
     136                         */
    126137                        while ( 0 !== get_space_used() ) {
    127138                                restore_current_blog();
     
    133144                        $cache_key_prefix = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['basedir'] ) );
    134145
    135                         // Clear the dirsize_cache
    136                         delete_transient( 'dirsize_cache' );
    137 
    138                         // Set the dirsize cache to our mock
     146                        // Clear the dirsize cache.
     147                        delete_transient( 'dirsize_cache' );
     148
     149                        // Set the dirsize cache to our mock.
    139150                        set_transient( 'dirsize_cache', $this->_get_mock_dirsize_cache_for_site( $blog_id ) );
    140151
     
    143154                        $this->assertSame( true, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) );
    144155
    145                         // Invalidation should also respect the directory tree up
    146                         // Should work fine with path to folder OR file
     156                        // Invalidation should also respect the directory tree up.
     157                        // Should work fine with path to directory OR file.
    147158                        clean_dirsize_cache( $upload_dir['basedir'] . '/2/1' );
    148159
     
    150161                        $this->assertSame( false, array_key_exists( $cache_key_prefix . '/2', get_transient( 'dirsize_cache' ) ) );
    151162
    152                         // Other cache paths should not be invalidated
    153                         $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) );
    154 
    155                         // Cleanup
    156                         $this->remove_added_uploads();
    157                         restore_current_blog();
    158                 }
    159 
    160                 /**
    161                  * Test whether the values from the dirsize_cache will be used correctly using a simple real upload
     163                        // Other cache paths should not be invalidated.
     164                        $this->assertSame( true, array_key_exists( $cache_key_prefix . '/1/1', get_transient( 'dirsize_cache' ) ) );
     165
     166                        // Cleanup.
     167                        $this->remove_added_uploads();
     168                        restore_current_blog();
     169                }
     170
     171                /**
     172                 * Test whether dirsize_cache values are used correctly with a simple real upload.
     173                 *
     174                 * @ticket 19879
    162175                 */
    163176                function test_get_dirsize_cache_in_recurse_dirsize_upload() {
     
    165178                        switch_to_blog( $blog_id );
    166179
    167                         // Our comparison of space relies on an initial value of 0. If a previous test has failed or if the
    168                         // src directory already contains a content directory with site content, then the initial expectation
    169                         // will be polluted. We create sites until an empty one is available.
    170                         while ( 0 !== get_space_used() ) {
    171                                 restore_current_blog();
    172                                 $blog_id = self::factory()->blog->create();
    173                                 switch_to_blog( $blog_id );
    174                         }
    175 
    176                         // Clear the dirsize_cache
     180                        /*
     181                         * Our comparison of space relies on an initial value of 0. If a previous test has failed
     182                         * or if the `src` directory already contains a content directory with site content, then
     183                         * the initial expectation will be polluted. We create sites until an empty one is available.
     184                         */
     185                        while ( 0 !== get_space_used() ) {
     186                                restore_current_blog();
     187                                $blog_id = self::factory()->blog->create();
     188                                switch_to_blog( $blog_id );
     189                        }
     190
     191                        // Clear the dirsize cache.
    177192                        delete_transient( 'dirsize_cache' );
    178193
     
    181196                        $this->assertSame( 0, recurse_dirsize( $upload_dir['path'] ) );
    182197
    183                         // Upload a file to the new site using wp_upload_bits.
     198                        // Upload a file to the new site using wp_upload_bits().
    184199                        $filename = __FUNCTION__ . '.jpg';
    185200                        $contents = __FUNCTION__ . '_contents';
     
    190205                        $this->assertSame( $size, $calc_size );
    191206
    192                         // dirsize_cache should now be filled after upload and recurse_dirsize call
     207                        // `dirsize_cache` should now be filled after upload and recurse_dirsize() call.
    193208                        $cache_path = untrailingslashit( str_replace( ABSPATH, '', $upload_dir['path'] ) );
    194209                        $this->assertSame( true, is_array( get_transient( 'dirsize_cache' ) ) );
    195210                        $this->assertSame( $size, get_transient( 'dirsize_cache' )[ $cache_path ] );
    196211
    197                         // Cleanup
    198                         $this->remove_added_uploads();
    199                         restore_current_blog();
    200                 }
    201 
    202                 /*
    203                  * Test whether the filter to calculate space for an existing directory works as expected
     212                        // Cleanup.
     213                        $this->remove_added_uploads();
     214                        restore_current_blog();
     215                }
     216
     217                /**
     218                 * Test whether the filter to calculate space for an existing directory works as expected.
     219                 *
     220                 * @ticket 19879
    204221                 */
    205222                function test_recurse_dirsize_calculate_current_dirsize_filter() {
     
    229246                }
    230247        }
     248
    231249endif;
Note: See TracChangeset for help on using the changeset viewer.