WordPress.org
Get WordPress

Make WordPress Core

Changeset 49628


Ignore:
Timestamp:
11/17/2020 03:36:02 PM (4 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.