WordPress.org

Make WordPress Core

Changeset 42776


Ignore:
Timestamp:
03/04/2018 09:42:12 PM (4 years ago)
Author:
SergeyBiryukov
Message:

Docs: Clarify return values and improve DocBlock formatting for verify_file_md5(), unzip_file(), _unzip_file_ziparchive(), _unzip_file_pclzip(), copy_dir(), WP_Filesystem().

See #42505.

File:
1 edited

Legend:

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

    r42775 r42776  
    10401040 * @since 3.7.0
    10411041 *
    1042  * @param string $filename The filename to check the MD5 of.
    1043  * @param string $expected_md5 The expected MD5 of the file, either a base64 encoded raw md5, or a hex-encoded md5
    1044  * @return bool|object WP_Error on failure, true on success, false when the MD5 format is unknown/unexpected
     1042 * @param string $filename     The filename to check the MD5 of.
     1043 * @param string $expected_md5 The expected MD5 of the file, either a base64-encoded raw md5,
     1044 *                             or a hex-encoded md5.
     1045 * @return bool|WP_Error True on success, false when the MD5 format is unknown/unexpected,
     1046 *                       WP_Error on failure.
    10451047 */
    10461048function verify_file_md5( $filename, $expected_md5 ) {
     
    10631065
    10641066/**
    1065  * Unzips a specified ZIP file to a location on the Filesystem via the WordPress Filesystem Abstraction.
    1066  * Assumes that WP_Filesystem() has already been called and set up. Does not extract a root-level __MACOSX directory, if present.
    1067  *
    1068  * Attempts to increase the PHP Memory limit to 256M before uncompressing,
    1069  * However, The most memory required shouldn't be much larger than the Archive itself.
     1067 * Unzips a specified ZIP file to a location on the filesystem via the WordPress
     1068 * Filesystem Abstraction.
     1069 *
     1070 * Assumes that WP_Filesystem() has already been called and set up. Does not extract
     1071 * a root-level __MACOSX directory, if present.
     1072 *
     1073 * Attempts to increase the PHP memory limit to 256M before uncompressing. However,
     1074 * the most memory required shouldn't be much larger than the archive itself.
    10701075 *
    10711076 * @since 2.5.0
    10721077 *
    1073  * @global WP_Filesystem_Base $wp_filesystem Subclass
    1074  *
    1075  * @param string $file Full path and filename of zip archive
    1076  * @param string $to Full path on the filesystem to extract archive to
    1077  * @return mixed WP_Error on failure, True on success
     1078 * @global WP_Filesystem_Base $wp_filesystem subclass.
     1079 *
     1080 * @param string $file Full path and filename of ZIP archive.
     1081 * @param string $to   Full path on the filesystem to extract archive to.
     1082 * @return true|WP_Error True on success, WP_Error on failure.
    10781083 */
    10791084function unzip_file( $file, $to ) {
     
    11331138
    11341139/**
    1135  * This function should not be called directly, use unzip_file instead. Attempts to unzip an archive using the ZipArchive class.
     1140 * Attempts to unzip an archive using the ZipArchive class.
     1141 *
     1142 * This function should not be called directly, use `unzip_file()` instead.
     1143 *
    11361144 * Assumes that WP_Filesystem() has already been called and set up.
    11371145 *
    11381146 * @since 3.0.0
    1139  * @see unzip_file
     1147 * @see unzip_file()
    11401148 * @access private
    11411149 *
    1142  * @global WP_Filesystem_Base $wp_filesystem Subclass
    1143  *
    1144  * @param string $file Full path and filename of zip archive
    1145  * @param string $to Full path on the filesystem to extract archive to
     1150 * @global WP_Filesystem_Base $wp_filesystem subclass.
     1151 *
     1152 * @param string $file       Full path and filename of ZIP archive.
     1153 * @param string $to         Full path on the filesystem to extract archive to.
    11461154 * @param array $needed_dirs A partial list of required folders needed to be created.
    1147  * @return mixed WP_Error on failure, True on success
     1155 * @return true|WP_Error True on success, WP_Error on failure.
    11481156 */
    11491157function _unzip_file_ziparchive( $file, $to, $needed_dirs = array() ) {
     
    12571265
    12581266/**
    1259  * This function should not be called directly, use unzip_file instead. Attempts to unzip an archive using the PclZip library.
     1267 * Attempts to unzip an archive using the PclZip library.
     1268 *
     1269 * This function should not be called directly, use `unzip_file()` instead.
     1270 *
    12601271 * Assumes that WP_Filesystem() has already been called and set up.
    12611272 *
    12621273 * @since 3.0.0
    1263  * @see unzip_file
     1274 * @see unzip_file()
    12641275 * @access private
    12651276 *
    1266  * @global WP_Filesystem_Base $wp_filesystem Subclass
    1267  *
    1268  * @param string $file Full path and filename of zip archive
    1269  * @param string $to Full path on the filesystem to extract archive to
     1277 * @global WP_Filesystem_Base $wp_filesystem subclass.
     1278 *
     1279 * @param string $file       Full path and filename of ZIP archive.
     1280 * @param string $to         Full path on the filesystem to extract archive to.
    12701281 * @param array $needed_dirs A partial list of required folders needed to be created.
    1271  * @return mixed WP_Error on failure, True on success
     1282 * @return true|WP_Error True on success, WP_Error on failure.
    12721283 */
    12731284function _unzip_file_pclzip( $file, $to, $needed_dirs = array() ) {
     
    13681379
    13691380/**
    1370  * Copies a directory from one location to another via the WordPress Filesystem Abstraction.
     1381 * Copies a directory from one location to another via the WordPress Filesystem
     1382 * Abstraction.
     1383 *
    13711384 * Assumes that WP_Filesystem() has already been called and setup.
    13721385 *
    13731386 * @since 2.5.0
    13741387 *
    1375  * @global WP_Filesystem_Base $wp_filesystem Subclass
    1376  *
    1377  * @param string $from source directory
    1378  * @param string $to destination directory
    1379  * @param array $skip_list a list of files/folders to skip copying
    1380  * @return mixed WP_Error on failure, True on success.
     1388 * @global WP_Filesystem_Base $wp_filesystem subclass.
     1389 *
     1390 * @param string $from     Source directory.
     1391 * @param string $to       Destination directory.
     1392 * @param array $skip_list A list of files/folders to skip copying.
     1393 * @return true|WP_Error True on success, WP_Error on failure.
    13811394 */
    13821395function copy_dir( $from, $to, $skip_list = array() ) {
     
    14271440/**
    14281441 * Initialises and connects the WordPress Filesystem Abstraction classes.
     1442 *
    14291443 * This function will include the chosen transport and attempt connecting.
    14301444 *
     
    14341448 * @since 2.5.0
    14351449 *
    1436  * @global WP_Filesystem_Base $wp_filesystem Subclass
     1450 * @global WP_Filesystem_Base $wp_filesystem subclass.
    14371451 *
    14381452 * @param array|false  $args                         Optional. Connection args, These are passed directly to
     
    14401454 * @param string|false $context                      Optional. Context for get_filesystem_method(). Default false.
    14411455 * @param bool         $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false.
    1442  * @return null|bool false on failure, true on success.
     1456 * @return bool|null True on success, false on failure, null if the filesystem method class file does not exist.
    14431457 */
    14441458function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_ownership = false ) {
     
    16231637 * @param bool   $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false.
    16241638 *
    1625  * @return bool False on failure, true on success.
     1639 * @return bool True on success, false on failure.
    16261640 */
    16271641function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) {
Note: See TracChangeset for help on using the changeset viewer.