Home       Trees       Indices       Help   
Package base :: Package includes :: Module file
[hide private]

Module file

source code

API for handling file uploads and server file management.
See Also:
Drupy Homepage, Drupal Homepage
Notes:

Author: Brendon Crawford

Copyright: 2008 Brendon Crawford

Contact: message144 at users dot sourceforge dot net

Version: 0.1

Functions [hide private]
 
create_url(path)
Create the download path to a file.		 source code
 
create_path(dest=0)
Make sure the destination is a complete path and resides in the file system directory, if it is not prepend the file system directory.		 source code
 
check_directory(directory, mode=0, form_item=None)
Check that the directory exists and is writable + Directories need to have execute permissions to be considered a directory by FTP servers, etc.		 source code
 
check_path(path)
Checks path to see if it is a directory, or a dir/file.		 source code
 
check_location(source, directory='')
Check if a file is really located inside directory + Should be used to make sure a file specified is really located within the directory to prevent exploits.		 source code
 
copy(source, dest=0, replace=0)
Copies a file to a new location.		 source code
 
destination(destination, replace)
Determines the destination path for a file depending on how replacement of existing files should be handled.		 source code
 
move(source, dest=0, replace=0)
Moves a file to a new location.		 source code
 
munge_filename(filename, extensions, alerts=True)
Munge the filename as needed for security purposes + For instance the file name "exploit.php.pps" would become "exploit.php_.pps".		 source code
 
unmunge_filename(filename)
Undo the effect of upload_munge_filename().		 source code
 
create_filename(basename, directory)
Create a full file path from a directory and filename + If a file with the specified name already exists, an alternative will be used.		 source code
 
delete(path)
Delete a file.		 source code
 
space_used(uid=None)
Determine total disk space used by a single user or the whole filesystem.		 source code
 
save_upload(source, validators={}, dest=False, replace=0)
Saves a file upload to a new location + The source file is validated as a proper upload and handled as such.		 source code
 
validate_name_length(file)
Check for files with names longer than we can store in the database.		 source code
 
validate_extensions(file, extensions)
Check that the filename ends with an allowed extension + This check is not enforced for the user #1.		 source code
 
validate_size(file, file_limit=0, user_limit=0)
Check that the file's size is below certain limits + This check is not enforced for the user #1.		 source code
 
validate_is_image(file)
Check that the file is recognized by image_get_info() as an image.		 source code
 
validate_image_resolution(file, maximum_dimensions=0, minimum_dimensions=0)
If the file is an image verify that its dimensions are within the specified maximum and minimum dimensions + Non-image files will be ignored.		 source code
 
save_data(data, dest, replace=0)
Save a string to the specified destination.		 source code
 
set_status(file, status)
Set the status of a file.		 source code
 
transfer(source, headers)
Transfer file using http to client + Pipes a file through Drupal to the client.		 source code
 
download()
Call plugins that implement hook_file_download() to find out if a file is accessible and what headers it should be transferred with + If a plugin returns -1 drupal_access_denied() will be returned + If one or more plugins returned headers the download will start with the returned headers + If no plugins respond drupal_not_found() will be returned.		 source code
 
scan_directory(dir, mask, nomask=['.', '..', 'CVS'], callback=0, recurse=True, key='filename', min_depth=0, depth=0)
Finds all files that match a given mask in a given directory.		 source code
 
directory_temp()
Determine the default temporary directory.		 source code
 
directory_path()
Determine the default 'files' directory.		 source code
 
upload_max_size()
Determine the maximum file upload size by querying the PHP settings.		 source code
Variables [hide private]
  __version__ = '$Revision: 1 $'
  FILE_DOWNLOADS_PUBLIC = 1
  FILE_DOWNLOADS_PRIVATE = 2
  FILE_CREATE_DIRECTORY = 1
  FILE_MODIFY_PERMISSIONS = 2
  FILE_EXISTS_RENAME = 0
  FILE_EXISTS_REPLACE = 1
  FILE_EXISTS_ERROR = 2
  FILE_STATUS_TEMPORARY = 0
  FILE_STATUS_PERMANENT = 1
Function Details [hide private]

create_url(path)

source code 
Create the download path to a file.
Parameters:
  • path - A string containing the path of the file to generate URL for.
Returns:
A string containing a URL that can be used to download the file.

create_path(dest=0)

source code 
Make sure the destination is a complete path and resides in the file system directory, if it is not prepend the file system directory.
Parameters:
  • dest - A string containing the path to verify + If this value is omitted, Drupal's 'files' directory will be used.
Returns:
A string containing the path to file, with file system directory appended if necessary, or False if the path is invalid (i.e + outside the configured 'files' or temp directories).

check_directory(directory, mode=0, form_item=None)

source code 
Check that the directory exists and is writable + Directories need to have execute permissions to be considered a directory by FTP servers, etc.
Parameters:
  • directory - A string containing the name of a directory path.
  • mode - A Boolean value to indicate if the directory should be created if it does not exist or made writable if it is read-only.
  • form_item - An optional string containing the name of a form item that any errors will be attached to + This is useful for settings forms that require the user to specify a writable directory + If it can't be made to work, a form error will be set preventing them from saving the settings.
Returns:
False when directory not found, or True when directory exists.

check_path(path)

source code 
Checks path to see if it is a directory, or a dir/file.
Parameters:
  • path - A string containing a file path + This will be set to the directory's path.
Returns:
If the directory is not in a Drupal writable directory, False is returned + Otherwise, the base name of the path is returned.

check_location(source, directory='')

source code 
Check if a file is really located inside directory + Should be used to make sure a file specified is really located within the directory to prevent exploits.
Parameters:
  • source - A string set to the file to check.
  • directory - A string where the file should be located.
Returns:
FALSE for invalid path or the real path of the source.

copy(source, dest=0, replace=0)

source code 
Copies a file to a new location. This is a powerful function that in many ways performs like an advanced version of copy(). - Checks if source and dest are valid and readable/writable. - Performs a file copy if source is not equal to dest. - If file already exists in dest either the call will error out, replace the file or rename the file based on the replace parameter.
Parameters:
  • source - A string specifying the file location of the original file. This parameter will contain the resulting destination filename in case of success.
  • dest - A string containing the directory source should be copied to. If this value is omitted, Drupal's 'files' directory will be used.
  • replace - Replace behavior when the destination file already exists. - FILE_EXISTS_REPLACE - Replace the existing file - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique - FILE_EXISTS_ERROR - Do nothing and return False.
Returns:
True for success, False for failure.

destination(destination, replace)

source code 
Determines the destination path for a file depending on how replacement of existing files should be handled.
Parameters:
  • destination - A string specifying the desired path.
  • replace - Replace behavior when the destination file already exists. - FILE_EXISTS_REPLACE - Replace the existing file - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique - FILE_EXISTS_ERROR - Do nothing and return False.
Returns:
The destination file path or False if the file already exists and FILE_EXISTS_ERROR was specified.

move(source, dest=0, replace=0)

source code 
Moves a file to a new location. - Checks if source and dest are valid and readable/writable. - Performs a file move if source is not equal to dest. - If file already exists in dest either the call will error out, replace the file or rename the file based on the replace parameter.
Parameters:
  • source - A string specifying the file location of the original file. This parameter will contain the resulting destination filename in case of success.
  • dest - A string containing the directory source should be copied to. If this value is omitted, Drupal's 'files' directory will be used.
  • replace - Replace behavior when the destination file already exists. - FILE_EXISTS_REPLACE - Replace the existing file - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique - FILE_EXISTS_ERROR - Do nothing and return False.
Returns:
True for success, False for failure.

munge_filename(filename, extensions, alerts=True)

source code 
Munge the filename as needed for security purposes + For instance the file name "exploit.php.pps" would become "exploit.php_.pps".
Parameters:
  • filename - The name of a file to modify.
  • extensions - A space separated list of extensions that should not be altered.
  • alerts - Whether alerts (watchdog, drupal_set_message()) should be displayed.
Returns:
filename The potentially modified filename.

unmunge_filename(filename)

source code 
Undo the effect of upload_munge_filename().
Parameters:
  • filename - string filename
Returns:
string

create_filename(basename, directory)

source code 
Create a full file path from a directory and filename + If a file with the specified name already exists, an alternative will be used.
Parameters:
  • basename - string filename
  • directory - string directory @return

delete(path)

source code 
Delete a file.
Parameters:
  • path - A string containing a file path.
Returns:
True for success, False for failure.

space_used(uid=None)

source code 
Determine total disk space used by a single user or the whole filesystem.
Parameters:
  • uid - An optional user id + A None value returns the total space used by all files.

save_upload(source, validators={}, dest=False, replace=0)

source code 
Saves a file upload to a new location + The source file is validated as a proper upload and handled as such. The file will be added to the files table as a temporary file. Temporary files are periodically cleaned + To make the file permanent file call file_set_status() to change its status.
Parameters:
  • source - A string specifying the name of the upload field to save.
  • validators - An optional, associative array of callback functions used to validate the file + The keys are function names and the values arrays of callback parameters which will be passed in after the user and file objects + The functions should return an array of error messages, an empty array indicates that the file passed validation. The functions will be called in the order specified.
  • dest - A string containing the directory source should be copied to + If this is not provided or is not writable, the temporary directory will be used.
  • replace - A boolean indicating whether an existing file of the same name in the destination directory should overwritten + A False value will generate a new, unique filename in the destination directory.
Returns:
An object containing the file information, or False in the event of an error.

validate_name_length(file)

source code 
Check for files with names longer than we can store in the database.
Parameters:
  • file - A Drupal file object.
Returns:
An array + If the file name is too long, it will contain an error message.

validate_extensions(file, extensions)

source code 
Check that the filename ends with an allowed extension + This check is not enforced for the user #1.
Parameters:
  • file - A Drupal file object.
  • extensions - A string with a space separated
Returns:
An array + If the file extension is not allowed, it will contain an error message.

validate_size(file, file_limit=0, user_limit=0)

source code 
Check that the file's size is below certain limits + This check is not enforced for the user #1.
Parameters:
  • file - A Drupal file object.
  • file_limit - An integer specifying the maximum file size in bytes. Zero indicates that no limit should be enforced.
  • $user_limit - An integer specifying the maximum number of bytes the user is allowed . Zero indicates that no limit should be enforced.
Returns:
An array + If the file size exceeds limits, it will contain an error message.

validate_is_image(file)

source code 
Check that the file is recognized by image_get_info() as an image.
Parameters:
  • file - A Drupal file object.
Returns:
An array + If the file is not an image, it will contain an error message.

validate_image_resolution(file, maximum_dimensions=0, minimum_dimensions=0)

source code 
If the file is an image verify that its dimensions are within the specified maximum and minimum dimensions + Non-image files will be ignored.
Parameters:
  • file - A Drupal file object + This function may resize the file affecting its size.
  • maximum_dimensions - An optional string in the form WIDTHxHEIGHT e.g + '640x480' or '85x85'. If an image toolkit is installed the image will be resized down to these dimensions + A value of 0 indicates no restriction on size, so resizing will be attempted.
  • minimum_dimensions - An optional string in the form WIDTHxHEIGHT. This will check that the image meets a minimum size + A value of 0 indicates no restriction.
Returns:
An array + If the file is an image and did not meet the requirements, it will contain an error message.

save_data(data, dest, replace=0)

source code 
Save a string to the specified destination.
Parameters:
  • data - A string containing the contents of the file.
  • dest - A string containing the destination location.
  • replace - Replace behavior when the destination file already exists. - FILE_EXISTS_REPLACE - Replace the existing file - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique - FILE_EXISTS_ERROR - Do nothing and return False.
Returns:
A string containing the resulting filename or False on error

set_status(file, status)

source code 
Set the status of a file.
Parameters:
  • file - A Drupal file object
  • status - A status value to set the file to.
Returns:
False on failure, True on success and file.status will contain the status.

transfer(source, headers)

source code 
Transfer file using http to client + Pipes a file through Drupal to the client.
Parameters:
  • source - File to transfer.
  • headers - An array of http headers to send along with file.

scan_directory(dir, mask, nomask=['.', '..', 'CVS'], callback=0, recurse=True, key='filename', min_depth=0, depth=0)

source code 
Finds all files that match a given mask in a given directory. Directories and files beginning with a period are excluded; this prevents hidden files and directories (such as SVN working directories) from being scanned.
Parameters:
  • dir - The base directory for the scan, without trailing slash.
  • mask - The regular expression of the files to find.
  • nomask - An array of files/directories to ignore.
  • callback - The callback function to call for each match.
  • recurse - When True, the directory scan will recurse the entire tree starting at the provided directory.
  • key - The key to be used for the returned array of files + Possible values are "filename", for the path starting with dir, "basename", for the basename of the file, and "name" for the name of the file without an extension.
  • min_depth - Minimum depth of directories to return files from.
  • depth - Current depth of recursion + This parameter is only used internally and should not be passed.
Returns:
An associative array (keyed on the provided key) of objects with "path", "basename", and "name" members corresponding to the matching files.

directory_temp()

source code 
Determine the default temporary directory.
Returns:
A string containing a temp directory.

directory_path()

source code 
Determine the default 'files' directory.
Returns:
A string containing the path to Drupal's 'files' directory.

upload_max_size()

source code 
Determine the maximum file upload size by querying the PHP settings.
Returns:
A file size limit in bytes based on the PHP upload_max_filesize and post_max_size

   Home       Trees       Indices       Help   
Generated by Epydoc 3.0.1 on Fri Sep 19 19:58:41 2008 http://epydoc.sourceforge.net