sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Browse Source 
See #49572.

git-svn-id: https://develop.svn.wordpress.org/trunk@48164 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov 2020-06-25 09:37:25 +00:00
parent 527c188079
commit b318e97530
1 changed files with 93 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
src/wp-admin/includes/file.php
View File

@ -65,27 +65,28 @@ $wp_file_descriptions = array(
); );
/** /**
* Get the description for standard WordPress theme files and other various standard * Gets the description for standard WordPress theme files.
* WordPress files
* *
* @since 1.5.0 * @since 1.5.0
* *
* @global array $wp_file_descriptions Theme file descriptions. * @global array $wp_file_descriptions Theme file descriptions.
* @global array $allowed_files List of allowed files. * @global array $allowed_files List of allowed files.
* @param string $file Filesystem path or filename *
* @param string $file Filesystem path or filename.
* @return string Description of file from $wp_file_descriptions or basename of $file if description doesn't exist. * @return string Description of file from $wp_file_descriptions or basename of $file if description doesn't exist.
* Appends 'Page Template' to basename of $file if the file is a page template * Appends 'Page Template' to basename of $file if the file is a page template.
*/ */
function get_file_description( $file ) { function get_file_description( $file ) {
global $wp_file_descriptions, $allowed_files; global $wp_file_descriptions, $allowed_files;
$dirname = pathinfo( $file, PATHINFO_DIRNAME ); $dirname = pathinfo( $file, PATHINFO_DIRNAME );
$file_path = $allowed_files[ $file ]; $file_path = $allowed_files[ $file ];
if ( isset( $wp_file_descriptions[ basename( $file ) ] ) && '.' === $dirname ) { if ( isset( $wp_file_descriptions[ basename( $file ) ] ) && '.' === $dirname ) {
return $wp_file_descriptions[ basename( $file ) ]; return $wp_file_descriptions[ basename( $file ) ];
} elseif ( file_exists( $file_path ) && is_file( $file_path ) ) { } elseif ( file_exists( $file_path ) && is_file( $file_path ) ) {
$template_data = implode( '', file( $file_path ) ); $template_data = implode( '', file( $file_path ) );
if ( preg_match( '|Template Name:(.*)$|mi', $template_data, $name ) ) { if ( preg_match( '|Template Name:(.*)$|mi', $template_data, $name ) ) {
/* translators: %s: Template name. */ /* translators: %s: Template name. */
return sprintf( __( '%s Page Template' ), _cleanup_header_comment( $name[1] ) ); return sprintf( __( '%s Page Template' ), _cleanup_header_comment( $name[1] ) );
@ -96,15 +97,16 @@ function get_file_description( $file ) {
} }
/** /**
* Get the absolute filesystem path to the root of the WordPress installation * Gets the absolute filesystem path to the root of the WordPress installation.
* *
* @since 1.5.0 * @since 1.5.0
* *
* @return string Full filesystem path to the root of the WordPress installation * @return string Full filesystem path to the root of the WordPress installation.
*/ */
function get_home_path() { function get_home_path() {
$home = set_url_scheme( get_option( 'home' ), 'http' ); $home = set_url_scheme( get_option( 'home' ), 'http' );
$siteurl = set_url_scheme( get_option( 'siteurl' ), 'http' ); $siteurl = set_url_scheme( get_option( 'siteurl' ), 'http' );
if ( ! empty( $home ) && 0 !== strcasecmp( $home, $siteurl ) ) { if ( ! empty( $home ) && 0 !== strcasecmp( $home, $siteurl ) ) {
$wp_path_rel_to_home = str_ireplace( $home, '', $siteurl ); /* $siteurl - $home */ $wp_path_rel_to_home = str_ireplace( $home, '', $siteurl ); /* $siteurl - $home */
$pos = strripos( str_replace( '\\', '/', $_SERVER['SCRIPT_FILENAME'] ), trailingslashit( $wp_path_rel_to_home ) ); $pos = strripos( str_replace( '\\', '/', $_SERVER['SCRIPT_FILENAME'] ), trailingslashit( $wp_path_rel_to_home ) );
@ -119,6 +121,7 @@ function get_home_path() {
/** /**
* Returns a listing of all files in the specified folder and all subdirectories up to 100 levels deep. * Returns a listing of all files in the specified folder and all subdirectories up to 100 levels deep.
*
* The depth of the recursiveness can be controlled by the $levels param. * The depth of the recursiveness can be controlled by the $levels param.
* *
* @since 2.6.0 * @since 2.6.0
@ -292,7 +295,7 @@ function wp_get_theme_file_editable_extensions( $theme ) {
} }
/** /**
* Print file editor templates (for plugins and themes). * Prints file editor templates (for plugins and themes).
* *
* @since 4.9.0 * @since 4.9.0
*/ */
@ -342,7 +345,7 @@ function wp_print_file_editor_templates() {
} }
/** /**
* Attempt to edit a file for a theme or plugin. * Attempts to edit a file for a theme or plugin.
* *
* When editing a PHP file, loopback requests will be made to the admin and the homepage * When editing a PHP file, loopback requests will be made to the admin and the homepage
* to attempt to see if there is a fatal error introduced. If so, the PHP change will be * to attempt to see if there is a fatal error introduced. If so, the PHP change will be
@ -500,6 +503,7 @@ function wp_edit_theme_plugin_file( $args ) {
if ( false === $written ) { if ( false === $written ) {
return new WP_Error( 'unable_to_write', __( 'Unable to write to file.' ) ); return new WP_Error( 'unable_to_write', __( 'Unable to write to file.' ) );
} }
wp_opcache_invalidate( $real_file, true ); wp_opcache_invalidate( $real_file, true );
if ( $is_active && 'php' === $extension ) { if ( $is_active && 'php' === $extension ) {
@ -629,17 +633,19 @@ function wp_edit_theme_plugin_file( $args ) {
/** /**
* Returns a filename of a Temporary unique file. * Returns a filename of a temporary unique file.
*
* Please note that the calling function must unlink() this itself. * Please note that the calling function must unlink() this itself.
* *
* The filename is based off the passed parameter or defaults to the current unix timestamp, * The filename is based off the passed parameter or defaults to the current unix timestamp,
* while the directory can either be passed as well, or by leaving it blank, default to a writable temporary directory. * while the directory can either be passed as well, or by leaving it blank, default to a writable
* temporary directory.
* *
* @since 2.6.0 * @since 2.6.0
* *
* @param string $filename Optional. Filename to base the Unique file off. Default empty. * @param string $filename Optional. Filename to base the Unique file off. Default empty.
* @param string $dir Optional. Directory to store the file in. Default empty. * @param string $dir Optional. Directory to store the file in. Default empty.
* @return string a writable filename * @return string A writable filename.
*/ */
function wp_tempnam( $filename = '', $dir = '' ) { function wp_tempnam( $filename = '', $dir = '' ) {
if ( empty( $dir ) ) { if ( empty( $dir ) ) {
@ -683,7 +689,8 @@ function wp_tempnam( $filename = '', $dir = '' ) {
* @since 1.5.0 * @since 1.5.0
* *
* @param string $file File the user is attempting to edit. * @param string $file File the user is attempting to edit.
* @param string[] $allowed_files Optional. Array of allowed files to edit. `$file` must match an entry exactly. * @param string[] $allowed_files Optional. Array of allowed files to edit.
* `$file` must match an entry exactly.
* @return string|void Returns the file name on success, dies on failure. * @return string|void Returns the file name on success, dies on failure.
*/ */
function validate_file_to_edit( $file, $allowed_files = array() ) { function validate_file_to_edit( $file, $allowed_files = array() ) {
@ -706,20 +713,25 @@ function validate_file_to_edit( $file, $allowed_files = array() ) {
} }
/** /**
* Handle PHP uploads in WordPress, sanitizing file names, checking extensions for mime type, * Handles PHP uploads in WordPress.
* and moving the file to the appropriate directory within the uploads directory. *
* Sanitizes file names, checks extensions for mime type, and moves the file
* to the appropriate directory within the uploads directory.
* *
* @access private * @access private
* @since 4.0.0 * @since 4.0.0
* *
* @see wp_handle_upload_error * @see wp_handle_upload_error
* *
* @param string[] $file Reference to a single element of `$_FILES`. Call the function once for each uploaded file. * @param string[] $file Reference to a single element of `$_FILES`.
* @param string[]|false $overrides An associative array of names => values to override default variables. Default false. * Call the function once for each uploaded file.
* @param string[]|false $overrides An associative array of names => values
* to override default variables. Default false.
* @param string $time Time formatted in 'yyyy/mm'. * @param string $time Time formatted in 'yyyy/mm'.
* @param string $action Expected value for `$_POST['action']`. * @param string $action Expected value for `$_POST['action']`.
* @return string[] On success, returns an associative array of file attributes. On failure, returns * @return string[] On success, returns an associative array of file attributes.
* `$overrides['upload_error_handler']( &$file, $message )` or `array( 'error' => $message )`. * On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
* or `array( 'error' => $message )`.
*/ */
function _wp_handle_upload( &$file, $overrides, $time, $action ) { function _wp_handle_upload( &$file, $overrides, $time, $action ) {
// The default error handler. // The default error handler.
@ -953,13 +965,14 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
* *
* @see _wp_handle_upload() * @see _wp_handle_upload()
* *
* @param array $file Reference to a single element of `$_FILES`. Call the function once for * @param array $file Reference to a single element of `$_FILES`.
* each uploaded file. * Call the function once for each uploaded file.
* @param array|bool $overrides Optional. An associative array of names=>values to override default * @param array|bool $overrides Optional. An associative array of names => values
* variables. Default false. * to override default variables. Default false.
* @param string $time Optional. Time formatted in 'yyyy/mm'. Default null. * @param string $time Optional. Time formatted in 'yyyy/mm'. Default null.
* @return array On success, returns an associative array of file attributes. On failure, returns * @return array On success, returns an associative array of file attributes.
* $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ). * On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
* or `array( 'error' => $message )`.
*/ */
function wp_handle_upload( &$file, $overrides = false, $time = null ) { function wp_handle_upload( &$file, $overrides = false, $time = null ) {
/* /*
@ -983,12 +996,14 @@ function wp_handle_upload( &$file, $overrides = false, $time = null ) {
* *
* @see _wp_handle_upload() * @see _wp_handle_upload()
* *
* @param array $file An array similar to that of a PHP `$_FILES` POST array * @param array $file Reference to a single element of `$_FILES`.
* @param array|bool $overrides Optional. An associative array of names=>values to override default * Call the function once for each uploaded file.
* variables. Default false. * @param array|bool $overrides Optional. An associative array of names => values
* to override default variables. Default false.
* @param string $time Optional. Time formatted in 'yyyy/mm'. Default null. * @param string $time Optional. Time formatted in 'yyyy/mm'. Default null.
* @return array On success, returns an associative array of file attributes. On failure, returns * @return array On success, returns an associative array of file attributes.
* $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ). * On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
* or `array( 'error' => $message )`.
*/ */
function wp_handle_sideload( &$file, $overrides = false, $time = null ) { function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
/* /*
@ -999,6 +1014,7 @@ function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
if ( isset( $overrides['action'] ) ) { if ( isset( $overrides['action'] ) ) {
$action = $overrides['action']; $action = $overrides['action'];
} }
return _wp_handle_upload( $file, $overrides, $time, $action ); return _wp_handle_upload( $file, $overrides, $time, $action );
} }
@ -1011,8 +1027,10 @@ function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
* @since 5.2.0 Signature Verification with SoftFail was added. * @since 5.2.0 Signature Verification with SoftFail was added.
* *
* @param string $url The URL of the file to download. * @param string $url The URL of the file to download.
* @param int $timeout The timeout for the request to download the file. Default 300 seconds. * @param int $timeout The timeout for the request to download the file.
* @param bool $signature_verification Whether to perform Signature Verification. Default false. * Default 300 seconds.
* @param bool $signature_verification Whether to perform Signature Verification.
* Default false.
* @return string|WP_Error Filename on success, WP_Error on failure. * @return string|WP_Error Filename on success, WP_Error on failure.
*/ */
function download_url( $url, $timeout = 300, $signature_verification = false ) { function download_url( $url, $timeout = 300, $signature_verification = false ) {
@ -1359,7 +1377,7 @@ function verify_file_signature( $filename, $signatures, $filename_for_errors = f
} }
/** /**
* Retrieve the list of signing keys trusted by WordPress. * Retrieves the list of signing keys trusted by WordPress.
* *
* @since 5.2.0 * @since 5.2.0
* *
@ -1741,6 +1759,7 @@ function copy_dir( $from, $to, $skip_list = array() ) {
return new WP_Error( 'copy_failed_copy_dir', __( 'Could not copy file.' ), $to . $filename ); return new WP_Error( 'copy_failed_copy_dir', __( 'Could not copy file.' ), $to . $filename );
} }
} }
wp_opcache_invalidate( $to . $filename ); wp_opcache_invalidate( $to . $filename );
} elseif ( 'd' === $fileinfo['type'] ) { } elseif ( 'd' === $fileinfo['type'] ) {
if ( ! $wp_filesystem->is_dir( $to . $filename ) ) { if ( ! $wp_filesystem->is_dir( $to . $filename ) ) {
@ -1779,11 +1798,15 @@ function copy_dir( $from, $to, $skip_list = array() ) {
* *
* @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass. * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass.
* *
* @param array|false $args Optional. Connection args, These are passed directly to * @param array|false $args Optional. Connection args, These are passed
* the `WP_Filesystem_*()` classes. Default false. * directly to the `WP_Filesystem_*()` classes.
* @param string|false $context Optional. Context for get_filesystem_method(). Default false. * Default false.
* @param bool $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false. * @param string|false $context Optional. Context for get_filesystem_method().
* @return bool|null True on success, false on failure, null if the filesystem method class file does not exist. * Default false.
* @param bool $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable.
* Default false.
* @return bool|null True on success, false on failure,
* null if the filesystem method class file does not exist.
*/ */
function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_ownership = false ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_ownership = false ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
global $wp_filesystem; global $wp_filesystem;
@ -1942,9 +1965,9 @@ function get_filesystem_method( $args = array(), $context = '', $allow_relaxed_f
* *
* @since 2.6.0 * @since 2.6.0
* *
* @param string $method Filesystem method to return. * @param string $method Filesystem method to return.
* @param array $args An array of connection details for the method. * @param array $args An array of connection details for the method.
* @param string $context Full path to the directory that is tested for being writable. * @param string $context Full path to the directory that is tested for being writable.
* @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable. * @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable.
*/ */
return apply_filters( 'filesystem_method', $method, $args, $context, $allow_relaxed_file_ownership ); return apply_filters( 'filesystem_method', $method, $args, $context, $allow_relaxed_file_ownership );
@ -1968,15 +1991,17 @@ function get_filesystem_method( $args = array(), $context = '', $allow_relaxed_f
* *
* @param string $form_post The URL to post the form to. * @param string $form_post The URL to post the form to.
* @param string $type Optional. Chosen type of filesystem. Default empty. * @param string $type Optional. Chosen type of filesystem. Default empty.
* @param bool|WP_Error $error Optional. Whether the current request has failed to connect, * @param bool|WP_Error $error Optional. Whether the current request has failed
* or an error object. Default false. * to connect, or an error object. Default false.
* @param string $context Optional. Full path to the directory that is tested for being * @param string $context Optional. Full path to the directory that is tested
* writable. Default empty. * for being writable. Default empty.
* @param array $extra_fields Optional. Extra `POST` fields to be checked for inclusion in * @param array $extra_fields Optional. Extra `POST` fields to be checked
* the post. Default null. * for inclusion in the post. Default null.
* @param bool $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false. * @param bool $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable.
* @return bool|array True if no filesystem credentials are required, false if they are required but have not been * Default false.
* provided, array of credentials if they are required and have been provided. * @return bool|array True if no filesystem credentials are required,
* false if they are required but have not been provided,
* array of credentials if they are required and have been provided.
*/ */
function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) { function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) {
global $pagenow; global $pagenow;
@ -2250,7 +2275,7 @@ function request_filesystem_credentials( $form_post, $type = '', $error = false,
} }
/** /**
* Print the filesystem credentials modal when needed. * Prints the filesystem credentials modal when needed.
* *
* @since 4.2.0 * @since 4.2.0
*/ */
@ -2278,22 +2303,22 @@ function wp_print_request_filesystem_credentials_modal() {
} }
/** /**
* Attempt to clear the opcode cache for an individual PHP file. * Attempts to clear the opcode cache for an individual PHP file.
* *
* This function can be called safely without having to check the file extension * This function can be called safely without having to check the file extension
* or availability of the OPcache extension. * or availability of the OPcache extension.
* *
* Whether or not invalidation is possible is cached to improve performance. * Whether or not invalidation is possible is cached to improve performance.
* *
* @since 5.5 * @since 5.5.0
* *
* @link https://www.php.net/manual/en/function.opcache-invalidate.php * @link https://www.php.net/manual/en/function.opcache-invalidate.php
* *
* @param string $filepath Path to the file, including extension, for which the opcode cache is to be cleared. * @param string $filepath Path to the file, including extension, for which the opcode cache is to be cleared.
* @param bool $force Invalidate even if the modification time is not newer than the file in cache. Default `false`. * @param bool $force Invalidate even if the modification time is not newer than the file in cache.
* * Default false.
* @return bool `true` if opcache was invalidated for `$filepath`, or there was nothing to invalidate. * @return bool True if opcache was invalidated for `$filepath`, or there was nothing to invalidate.
* `false` if opcache invalidation is not available, or is disabled via filter. * False if opcache invalidation is not available, or is disabled via filter.
*/ */
function wp_opcache_invalidate( $filepath, $force = false ) { function wp_opcache_invalidate( $filepath, $force = false ) {
static $can_invalidate = null; static $can_invalidate = null;
@ -2309,19 +2334,20 @@ function wp_opcache_invalidate( $filepath, $force = false ) {
* If the host has this set, check whether the path in `opcache.restrict_api` matches * If the host has this set, check whether the path in `opcache.restrict_api` matches
* the beginning of the path of the origin file. * the beginning of the path of the origin file.
* *
* `$_SERVER['SCRIPT_FILENAME']` approximates the origin file's path, but * `$_SERVER['SCRIPT_FILENAME']` approximates the origin file's path, but `realpath()`
* `realpath()` is necessary because `SCRIPT_FILENAME` can be a relative path * is necessary because `SCRIPT_FILENAME` can be a relative path when run from CLI.
* when run from CLI.
* *
* For more details, see: * For more details, see:
* - https://www.php.net/manual/en/opcache.configuration.php * - https://www.php.net/manual/en/opcache.configuration.php
* - https://www.php.net/manual/en/reserved.variables.server.php * - https://www.php.net/manual/en/reserved.variables.server.php
* - https://core.trac.wordpress.org/ticket/36455 * - https://core.trac.wordpress.org/ticket/36455
*/ */
if ( null === $can_invalidate ) { if ( null === $can_invalidate
$can_invalidate = function_exists( 'opcache_invalidate' ) && && function_exists( 'opcache_invalidate' )
( ! ini_get( 'opcache.restrict_api' ) || && ( ! ini_get( 'opcache.restrict_api' )
stripos( realpath( $_SERVER['SCRIPT_FILENAME'] ), ini_get( 'opcache.restrict_api' ) ) === 0 ); || stripos( realpath( $_SERVER['SCRIPT_FILENAME'] ), ini_get( 'opcache.restrict_api' ) ) === 0 )
) {
$can_invalidate = true;
} }
// If invalidation is not available, return early. // If invalidation is not available, return early.
@ -2337,9 +2363,9 @@ function wp_opcache_invalidate( $filepath, $force = false ) {
/** /**
* Filters whether to invalidate a file from the opcode cache. * Filters whether to invalidate a file from the opcode cache.
* *
* @since 5.5 * @since 5.5.0
* *
* @param bool $will_invalidate Whether WordPress will invalidate `$filename`. Default `true`. * @param bool $will_invalidate Whether WordPress will invalidate `$filename`. Default true.
* @param string $filename The PHP filename to invalidate. * @param string $filename The PHP filename to invalidate.
*/ */
if ( apply_filters( 'wp_opcache_invalidate_file', true, $filepath ) ) { if ( apply_filters( 'wp_opcache_invalidate_file', true, $filepath ) ) {