diff --git a/core/includes/file.inc b/core/includes/file.inc index 09af50f..9bb27e9 100644 --- a/core/includes/file.inc +++ b/core/includes/file.inc @@ -70,11 +70,7 @@ const FILE_EXISTS_ERROR = 2; const FILE_STATUS_PERMANENT = 1; /** - * Methods to manage a registry of stream wrappers. - */ - -/** - * Drupal stream wrapper registry. + * Provides Drupal stream wrapper registry. * * A stream wrapper is an abstraction of a file system that allows Drupal to * use the same set of methods to access both local files and remote resources. @@ -206,7 +202,7 @@ function file_uri_scheme($uri) { } /** - * Check that the scheme of a stream URI is valid. + * Checks that the scheme of a stream URI is valid. * * Confirms that there is a registered stream handler for the provided scheme * and that it is callable. This is useful if you want to confirm a valid @@ -232,7 +228,7 @@ function file_stream_wrapper_valid_scheme($scheme) { /** - * Returns the part of an URI after the schema. + * Returns the part of a URI after the schema. * * @param $uri * A stream, referenced as "scheme://target". @@ -252,7 +248,7 @@ function file_uri_target($uri) { } /** - * Get the default file stream implementation. + * Gets the default file stream implementation. * * @return * 'public', 'private' or any other file scheme defined as the default. @@ -322,7 +318,7 @@ function file_stream_wrapper_get_instance_by_uri($uri) { } /** - * Returns a reference to the stream wrapper class responsible for a given scheme. + * Returns a reference to the stream wrapper class responsible for a scheme. * * This helper method returns a stream instance using a scheme. That is, the * passed string does not contain a "://". For example, "public" is a scheme @@ -418,7 +414,7 @@ function file_create_url($uri) { } /** - * Check that the directory exists and is writable. + * Checks that the directory exists and is writable. * * Directories need to have execute permissions to be considered a directory by * FTP servers, etc. @@ -460,7 +456,7 @@ function file_prepare_directory(&$directory, $options = FILE_MODIFY_PERMISSIONS) } /** - * If missing, create a .htaccess file in each Drupal files directory. + * Creates a .htaccess file in each Drupal files directory if it is missing. */ function file_ensure_htaccess() { file_save_htaccess('public://', FALSE); @@ -471,7 +467,7 @@ function file_ensure_htaccess() { } /** - * Creates an .htaccess file in the given directory. + * Creates a .htaccess file in the given directory. * * @param $directory * The directory. @@ -539,7 +535,7 @@ function file_load_multiple($fids = array(), $conditions = array()) { } /** - * Load a file object from the database. + * Loads a single file object from the database. * * @param $fid * A file ID. @@ -556,7 +552,7 @@ function file_load($fid) { } /** - * Save a file object to the database. + * Saves a file object to the database. * * If the $file->fid is not set a new record will be added. * @@ -798,7 +794,7 @@ function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS } /** - * Determine whether the URI has a valid scheme for file API operations. + * Determines whether the URI has a valid scheme for file API operations. * * There must be a scheme and it must be a Drupal-provided scheme like * 'public', 'private', 'temporary', or an extension provided with @@ -927,7 +923,7 @@ function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXIST } /** - * Given a relative path, construct a URI into Drupal's default files location. + * Constructs a URI to Drupal's default files location given a relative path. */ function file_build_uri($path) { $uri = file_default_scheme() . '://' . $path; @@ -935,8 +931,7 @@ function file_build_uri($path) { } /** - * Determines the destination path for a file depending on how replacement of - * existing files should be handled. + * Determines the destination path for a file. * * @param $destination * A string specifying the desired final URI or filepath. @@ -973,7 +968,7 @@ function file_destination($destination, $replace) { } /** - * Move a file to a new location and update the file's database entry. + * Moves a file to a new location and update the file's database entry. * * Moving a file is performed by copying the file to the new location and then * deleting the original. @@ -1053,8 +1048,7 @@ function file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS } /** - * Move a file to a new location without calling any hooks or making any - * changes to the database. + * Moves a file to a new location without database changes or hook invocation. * * @param $source * A string specifying the filepath or URI of the original file. @@ -1083,7 +1077,7 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST } /** - * Modify a filename as needed for security purposes. + * Modifies a filename as needed for security purposes. * * Munging a file name prevents unknown file extensions from masking exploit * files. When web servers such as Apache decide how to process a URL request, @@ -1147,7 +1141,7 @@ function file_munge_filename($filename, $extensions, $alerts = TRUE) { } /** - * Undo the effect of file_munge_filename(). + * Undoes the effect of file_munge_filename(). * * @param $filename * String with the filename to be unmunged. @@ -1160,7 +1154,7 @@ function file_unmunge_filename($filename) { } /** - * Create a full file path from a directory and filename. + * Creates a full file path from a directory and filename. * * If a file with the specified name already exists, an alternative will be * used. @@ -1215,7 +1209,7 @@ function file_create_filename($basename, $directory) { } /** - * Delete a file and its database record. + * Deletes a file and its database record. * * If the $force parameter is not TRUE, file_usage_list() will be called to * determine if the file is being used by any modules. If the file is being @@ -1276,8 +1270,7 @@ function file_delete(stdClass $file, $force = FALSE) { } /** - * Delete a file without calling any hooks or making any changes to the - * database. + * Deletes a file without database changes or hook invocations. * * This function should be used when the file to be deleted does not have an * entry recorded in the files table. @@ -1313,7 +1306,7 @@ function file_unmanaged_delete($path) { } /** - * Recursively delete all files and directories in the specified filepath. + * Deletes all files and directories in the specified filepath recursively. * * If the specified path is a directory then the function will call itself * recursively to process the contents. Once the contents have been removed the @@ -1351,7 +1344,7 @@ function file_unmanaged_delete_recursive($path) { } /** - * Determine total disk space used by a single user or the whole filesystem. + * Determines total disk space used by a single user or the whole filesystem. * * @param $uid * Optional. A user id, specifying NULL returns the total space used by all @@ -1619,7 +1612,7 @@ function drupal_move_uploaded_file($filename, $uri) { } /** - * Check that a file meets the criteria specified by the validators. + * Checks that a file meets the criteria specified by the validators. * * After executing the validator callbacks specified hook_file_validate() will * also be called to allow other modules to report errors about the file. @@ -1654,7 +1647,7 @@ function file_validate(stdClass &$file, $validators = array()) { } /** - * Check for files with names longer than we can store in the database. + * Checks for files with names longer than can be stored in the database. * * @param $file * A Drupal file object. @@ -1675,7 +1668,7 @@ function file_validate_name_length(stdClass $file) { } /** - * Check that the filename ends with an allowed extension. + * Checks that the filename ends with an allowed extension. * * @param $file * A Drupal file object. @@ -1699,7 +1692,7 @@ function file_validate_extensions(stdClass $file, $extensions) { } /** - * Check that the file's size is below certain limits. + * Checks that the file's size is below certain limits. * * This check is not enforced for the user #1. * @@ -1738,7 +1731,7 @@ function file_validate_size(stdClass $file, $file_limit = 0, $user_limit = 0) { } /** - * Check that the file is recognized by image_get_info() as an image. + * Checks that the file is recognized by image_get_info() as an image. * * @param $file * A Drupal file object. @@ -1760,7 +1753,7 @@ function file_validate_is_image(stdClass $file) { } /** - * Verify that image dimensions are within the specified maximum and minimum. + * Verifies that image dimensions are within the specified maximum and minimum. * * Non-image files will be ignored. If a image toolkit is available the image * will be scaled to fit within the desired maximum dimensions. @@ -1818,7 +1811,7 @@ function file_validate_image_resolution(stdClass $file, $maximum_dimensions = 0, } /** - * Save a string to the specified destination and create a database file entry. + * Saves a file to the specified destination and creates a database entry. * * @param $data * A string containing the contents of the file. @@ -1882,7 +1875,7 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM } /** - * Save a string to the specified destination without invoking file API. + * Saves a file to the specified destination without invoking file API. * * This function is identical to file_save_data() except the file will not be * saved to the {file_managed} table and none of the file_* hooks will be @@ -1920,7 +1913,7 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX } /** - * Transfer file using HTTP to client. + * Transfers a file to the client using HTTP. * * Pipes a file through Drupal to the client. * @@ -1953,7 +1946,9 @@ function file_transfer($uri, $headers) { } /** - * Menu handler for private file transfers. + * Page callback: Handles private file transfers. + * + * Path: system/temporary * * Call modules that implement hook_file_download() to find out if a file is * accessible and what headers it should be transferred with. If one or more @@ -1963,6 +1958,7 @@ function file_transfer($uri, $headers) { * If the file does not exist drupal_not_found() will be returned. * * @see hook_file_download() + * @see system_menu() */ function file_download() { // Merge remainder of arguments from GET['q'], into relative file path. @@ -2072,7 +2068,7 @@ function file_scan_directory($dir, $mask, $options = array(), $depth = 0) { } /** - * Determine the maximum file upload size by querying the PHP settings. + * Determines the maximum file upload size by querying the PHP settings. * * @return * A file size limit in bytes based on the PHP upload_max_filesize and @@ -2096,7 +2092,7 @@ function file_upload_max_size() { } /** - * Determine an Internet Media Type, or MIME type from a filename. + * Determines an Internet Media Type or MIME type from a filename. * * @param $uri * A string containing the URI, path, or filename. @@ -2125,7 +2121,7 @@ function file_get_mimetype($uri, $mapping = NULL) { } /** - * Set the permissions on a file or directory. + * Sets the permissions on a file or directory. * * This function will use the 'file_chmod_directory' and 'file_chmod_file' * variables for the default modes for directories and uploaded/generated @@ -2316,7 +2312,7 @@ function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) { } /** - * Remove a directory. + * Removes a directory. * * PHP's rmdir() is broken on Windows, as it can fail to remove a directory * when it has a read-only flag set. @@ -2387,7 +2383,7 @@ function drupal_tempnam($directory, $prefix) { } /** - * Get the path of system-appropriate temporary directory. + * Gets the path of system-appropriate temporary directory. */ function file_directory_temp() { $temporary_directory = variable_get('file_temporary_path', NULL);