WordPress.org
Get WordPress

Make WordPress Core

Changeset 48164


Ignore:
Timestamp:
06/25/2020 09:37:25 AM (5 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve DocBlocks in wp-admin/includes/file.php per the documentation standards.

See #49572.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/file.php

    r48163 r48164  
    6666
    6767/**
    68  * Get the description for standard WordPress theme files and other various standard
    69  * WordPress files
     68 * Gets the description for standard WordPress theme files.
    7069 *
    7170 * @since 1.5.0
    … …  
    7372 * @global array $wp_file_descriptions Theme file descriptions.
    7473 * @global array $allowed_files        List of allowed files.
    75  * @param string $file Filesystem path or filename
     74 *
     75 * @param string $file Filesystem path or filename.
    7676 * @return string Description of file from $wp_file_descriptions or basename of $file if description doesn't exist.
    77  *                Appends 'Page Template' to basename of $file if the file is a page template
     77 *                Appends 'Page Template' to basename of $file if the file is a page template.
    7878 */
    7979function get_file_description( $file ) {
    8080    global $wp_file_descriptions, $allowed_files;
    8181
    82     $dirname = pathinfo( $file, PATHINFO_DIRNAME );
    83 
     82    $dirname   = pathinfo( $file, PATHINFO_DIRNAME );
    8483    $file_path = $allowed_files[ $file ];
     84
    8585    if ( isset( $wp_file_descriptions[ basename( $file ) ] ) && '.' === $dirname ) {
    8686        return $wp_file_descriptions[ basename( $file ) ];
    8787    } elseif ( file_exists( $file_path ) && is_file( $file_path ) ) {
    8888        $template_data = implode( '', file( $file_path ) );
     89
    8990        if ( preg_match( '|Template Name:(.*)$|mi', $template_data, $name ) ) {
    9091            /* translators: %s: Template name. */
    … …  
    9798
    9899/**
    99  * Get the absolute filesystem path to the root of the WordPress installation
     100 * Gets the absolute filesystem path to the root of the WordPress installation.
    100101 *
    101102 * @since 1.5.0
    102103 *
    103  * @return string Full filesystem path to the root of the WordPress installation
     104 * @return string Full filesystem path to the root of the WordPress installation.
    104105 */
    105106function get_home_path() {
    106107    $home    = set_url_scheme( get_option( 'home' ), 'http' );
    107108    $siteurl = set_url_scheme( get_option( 'siteurl' ), 'http' );
     109
    108110    if ( ! empty( $home ) && 0 !== strcasecmp( $home, $siteurl ) ) {
    109111        $wp_path_rel_to_home = str_ireplace( $home, '', $siteurl ); /* $siteurl - $home */
    … …  
    120122/**
    121123 * Returns a listing of all files in the specified folder and all subdirectories up to 100 levels deep.
     124 *
    122125 * The depth of the recursiveness can be controlled by the $levels param.
    123126 *
    … …  
    293296
    294297/**
    295  * Print file editor templates (for plugins and themes).
     298 * Prints file editor templates (for plugins and themes).
    296299 *
    297300 * @since 4.9.0
    … …  
    343346
    344347/**
    345  * Attempt to edit a file for a theme or plugin.
     348 * Attempts to edit a file for a theme or plugin.
    346349 *
    347350 * When editing a PHP file, loopback requests will be made to the admin and the homepage
    … …  
    501504        return new WP_Error( 'unable_to_write', __( 'Unable to write to file.' ) );
    502505    }
     506
    503507    wp_opcache_invalidate( $real_file, true );
    504508
    … …  
    630634
    631635/**
    632  * Returns a filename of a Temporary unique file.
     636 * Returns a filename of a temporary unique file.
     637 *
    633638 * Please note that the calling function must unlink() this itself.
    634639 *
    635640 * The filename is based off the passed parameter or defaults to the current unix timestamp,
    636  * while the directory can either be passed as well, or by leaving it blank, default to a writable temporary directory.
     641 * while the directory can either be passed as well, or by leaving it blank, default to a writable
     642 * temporary directory.
    637643 *
    638644 * @since 2.6.0
    … …  
    640646 * @param string $filename Optional. Filename to base the Unique file off. Default empty.
    641647 * @param string $dir      Optional. Directory to store the file in. Default empty.
    642  * @return string a writable filename
     648 * @return string A writable filename.
    643649 */
    644650function wp_tempnam( $filename = '', $dir = '' ) {
    … …  
    684690 *
    685691 * @param string   $file          File the user is attempting to edit.
    686  * @param string[] $allowed_files Optional. Array of allowed files to edit. `$file` must match an entry exactly.
     692 * @param string[] $allowed_files Optional. Array of allowed files to edit.
     693 *                                `$file` must match an entry exactly.
    687694 * @return string|void Returns the file name on success, dies on failure.
    688695 */
    … …  
    707714
    708715/**
    709  * Handle PHP uploads in WordPress, sanitizing file names, checking extensions for mime type,
    710  * and moving the file to the appropriate directory within the uploads directory.
     716 * Handles PHP uploads in WordPress.
     717 *
     718 * Sanitizes file names, checks extensions for mime type, and moves the file
     719 * to the appropriate directory within the uploads directory.
    711720 *
    712721 * @access private
    … …  
    715724 * @see wp_handle_upload_error
    716725 *
    717  * @param string[]       $file      Reference to a single element of `$_FILES`. Call the function once for each uploaded file.
    718  * @param string[]|false $overrides An associative array of names => values to override default variables. Default false.
     726 * @param string[]       $file      Reference to a single element of `$_FILES`.
     727 *                                  Call the function once for each uploaded file.
     728 * @param string[]|false $overrides An associative array of names => values
     729 *                                  to override default variables. Default false.
    719730 * @param string         $time      Time formatted in 'yyyy/mm'.
    720731 * @param string         $action    Expected value for `$_POST['action']`.
    721  * @return string[] On success, returns an associative array of file attributes. On failure, returns
    722  *                  `$overrides['upload_error_handler']( &$file, $message )` or `array( 'error' => $message )`.
     732 * @return string[] On success, returns an associative array of file attributes.
     733 *                  On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
     734 *                  or `array( 'error' => $message )`.
    723735 */
    724736function _wp_handle_upload( &$file, $overrides, $time, $action ) {
    … …  
    954966 * @see _wp_handle_upload()
    955967 *
    956  * @param array      $file      Reference to a single element of `$_FILES`. Call the function once for
    957  *                              each uploaded file.
    958  * @param array|bool $overrides Optional. An associative array of names=>values to override default
    959  *                              variables. Default false.
     968 * @param array      $file      Reference to a single element of `$_FILES`.
     969 *                              Call the function once for each uploaded file.
     970 * @param array|bool $overrides Optional. An associative array of names => values
     971 *                              to override default variables. Default false.
    960972 * @param string     $time      Optional. Time formatted in 'yyyy/mm'. Default null.
    961  * @return array On success, returns an associative array of file attributes. On failure, returns
    962  *               $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ).
     973 * @return array On success, returns an associative array of file attributes.
     974 *               On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
     975 *               or `array( 'error' => $message )`.
    963976 */
    964977function wp_handle_upload( &$file, $overrides = false, $time = null ) {
    … …  
    984997 * @see _wp_handle_upload()
    985998 *
    986  * @param array      $file      An array similar to that of a PHP `$_FILES` POST array
    987  * @param array|bool $overrides Optional. An associative array of names=>values to override default
    988  *                              variables. Default false.
     999 * @param array      $file      Reference to a single element of `$_FILES`.
     1000 *                              Call the function once for each uploaded file.
     1001 * @param array|bool $overrides Optional. An associative array of names => values
     1002 *                              to override default variables. Default false.
    9891003 * @param string     $time      Optional. Time formatted in 'yyyy/mm'. Default null.
    990  * @return array On success, returns an associative array of file attributes. On failure, returns
    991  *               $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ).
     1004 * @return array On success, returns an associative array of file attributes.
     1005 *               On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
     1006 *               or `array( 'error' => $message )`.
    9921007 */
    9931008function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
    … …  
    10001015        $action = $overrides['action'];
    10011016    }
     1017
    10021018    return _wp_handle_upload( $file, $overrides, $time, $action );
    10031019}
    … …  
    10121028 *
    10131029 * @param string $url                    The URL of the file to download.
    1014  * @param int    $timeout                The timeout for the request to download the file. Default 300 seconds.
    1015  * @param bool   $signature_verification Whether to perform Signature Verification. Default false.
     1030 * @param int    $timeout                The timeout for the request to download the file.
     1031 *                                       Default 300 seconds.
     1032 * @param bool   $signature_verification Whether to perform Signature Verification.
     1033 *                                       Default false.
    10161034 * @return string|WP_Error Filename on success, WP_Error on failure.
    10171035 */
    … …  
    13601378
    13611379/**
    1362  * Retrieve the list of signing keys trusted by WordPress.
     1380 * Retrieves the list of signing keys trusted by WordPress.
    13631381 *
    13641382 * @since 5.2.0
    … …  
    17421760                }
    17431761            }
     1762
    17441763            wp_opcache_invalidate( $to . $filename );
    17451764        } elseif ( 'd' === $fileinfo['type'] ) {
    … …  
    17801799 * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass.
    17811800 *
    1782  * @param array|false  $args                         Optional. Connection args, These are passed directly to
    1783  *                                                   the `WP_Filesystem_*()` classes. Default false.
    1784  * @param string|false $context                      Optional. Context for get_filesystem_method(). Default false.
    1785  * @param bool         $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false.
    1786  * @return bool|null True on success, false on failure, null if the filesystem method class file does not exist.
     1801 * @param array|false  $args                         Optional. Connection args, These are passed
     1802 *                                                   directly to the `WP_Filesystem_*()` classes.
     1803 *                                                   Default false.
     1804 * @param string|false $context                      Optional. Context for get_filesystem_method().
     1805 *                                                   Default false.
     1806 * @param bool         $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable.
     1807 *                                                   Default false.
     1808 * @return bool|null True on success, false on failure,
     1809 *                   null if the filesystem method class file does not exist.
    17871810 */
    17881811function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_ownership = false ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
    … …  
    19431966     * @since 2.6.0
    19441967     *
    1945      * @param string $method  Filesystem method to return.
    1946      * @param array  $args    An array of connection details for the method.
    1947      * @param string $context Full path to the directory that is tested for being writable.
     1968     * @param string $method                       Filesystem method to return.
     1969     * @param array  $args                         An array of connection details for the method.
     1970     * @param string $context                      Full path to the directory that is tested for being writable.
    19481971     * @param bool   $allow_relaxed_file_ownership Whether to allow Group/World writable.
    19491972     */
    … …  
    19691992 * @param string        $form_post                    The URL to post the form to.
    19701993 * @param string        $type                         Optional. Chosen type of filesystem. Default empty.
    1971  * @param bool|WP_Error $error                        Optional. Whether the current request has failed to connect,
    1972  *                                                    or an error object. Default false.
    1973  * @param string        $context                      Optional. Full path to the directory that is tested for being
    1974  *                                                    writable. Default empty.
    1975  * @param array         $extra_fields                 Optional. Extra `POST` fields to be checked for inclusion in
    1976  *                                                    the post. Default null.
    1977  * @param bool          $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false.
    1978  * @return bool|array True if no filesystem credentials are required, false if they are required but have not been
    1979  *                    provided, array of credentials if they are required and have been provided.
     1994 * @param bool|WP_Error $error                        Optional. Whether the current request has failed
     1995 *                                                    to connect, or an error object. Default false.
     1996 * @param string        $context                      Optional. Full path to the directory that is tested
     1997 *                                                    for being writable. Default empty.
     1998 * @param array         $extra_fields                 Optional. Extra `POST` fields to be checked
     1999 *                                                    for inclusion in the post. Default null.
     2000 * @param bool          $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable.
     2001 *                                                    Default false.
     2002 * @return bool|array True if no filesystem credentials are required,
     2003 *                    false if they are required but have not been provided,
     2004 *                    array of credentials if they are required and have been provided.
    19802005 */
    19812006function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) {
    … …  
    22512276
    22522277/**
    2253  * Print the filesystem credentials modal when needed.
     2278 * Prints the filesystem credentials modal when needed.
    22542279 *
    22552280 * @since 4.2.0
    … …  
    22792304
    22802305/**
    2281  * Attempt to clear the opcode cache for an individual PHP file.
     2306 * Attempts to clear the opcode cache for an individual PHP file.
    22822307 *
    22832308 * This function can be called safely without having to check the file extension
    … …  
    22862311 * Whether or not invalidation is possible is cached to improve performance.
    22872312 *
    2288  * @since 5.5
     2313 * @since 5.5.0
    22892314 *
    22902315 * @link https://www.php.net/manual/en/function.opcache-invalidate.php
    22912316 *
    22922317 * @param string $filepath Path to the file, including extension, for which the opcode cache is to be cleared.
    2293  * @param bool   $force    Invalidate even if the modification time is not newer than the file in cache. Default `false`.
    2294  *
    2295  * @return bool `true` if opcache was invalidated for `$filepath`, or there was nothing to invalidate.
    2296  *              `false` if opcache invalidation is not available, or is disabled via filter.
     2318 * @param bool   $force    Invalidate even if the modification time is not newer than the file in cache.
     2319 *                         Default false.
     2320 * @return bool True if opcache was invalidated for `$filepath`, or there was nothing to invalidate.
     2321 *              False if opcache invalidation is not available, or is disabled via filter.
    22972322 */
    22982323function wp_opcache_invalidate( $filepath, $force = false ) {
    … …  
    23102335     * the beginning of the path of the origin file.
    23112336     *
    2312      * `$_SERVER['SCRIPT_FILENAME']` approximates the origin file's path, but
    2313      * `realpath()` is necessary because `SCRIPT_FILENAME` can be a relative path
    2314      * when run from CLI.
     2337     * `$_SERVER['SCRIPT_FILENAME']` approximates the origin file's path, but `realpath()`
     2338     * is necessary because `SCRIPT_FILENAME` can be a relative path when run from CLI.
    23152339     *
    23162340     * For more details, see:
    … …  
    23192343     * - https://core.trac.wordpress.org/ticket/36455
    23202344     */
    2321     if ( null === $can_invalidate ) {
    2322         $can_invalidate = function_exists( 'opcache_invalidate' ) &&
    2323             ( ! ini_get( 'opcache.restrict_api' ) ||
    2324                 stripos( realpath( $_SERVER['SCRIPT_FILENAME'] ), ini_get( 'opcache.restrict_api' ) ) === 0 );
     2345    if ( null === $can_invalidate
     2346        && function_exists( 'opcache_invalidate' )
     2347        && ( ! ini_get( 'opcache.restrict_api' )
     2348            || stripos( realpath( $_SERVER['SCRIPT_FILENAME'] ), ini_get( 'opcache.restrict_api' ) ) === 0 )
     2349    ) {
     2350        $can_invalidate = true;
    23252351    }
    23262352
    … …  
    23382364     * Filters whether to invalidate a file from the opcode cache.
    23392365     *
    2340      * @since 5.5
    2341      *
    2342      * @param bool   $will_invalidate Whether WordPress will invalidate `$filename`. Default `true`.
     2366     * @since 5.5.0
     2367     *
     2368     * @param bool   $will_invalidate Whether WordPress will invalidate `$filename`. Default true.
    23432369     * @param string $filename        The PHP filename to invalidate.
    23442370     */
Note: See TracChangeset for help on using the changeset viewer.