File interface


Enumerations
enum	FILE_DOWNLOADS_PUBLIC
enum	FILE_DOWNLOADS_PRIVATE
enum	FILE_CREATE_DIRECTORY
enum	FILE_MODIFY_PERMISSIONS
enum	FILE_EXISTS_RENAME
enum	FILE_EXISTS_REPLACE
enum	FILE_EXISTS_ERROR
enum	FILE_STATUS_TEMPORARY
enum	FILE_STATUS_PERMANENT
Functions
	file_create_url ($path)
	file_create_path ($dest=0)
	file_check_directory (&$directory, $mode=0, $form_item=NULL)
	file_check_path (&$path)
	file_check_location ($source, $directory= '')
	file_copy (&$source, $dest=0, $replace=FILE_EXISTS_RENAME)
	file_destination ($destination, $replace)
	file_move (&$source, $dest=0, $replace=FILE_EXISTS_RENAME)
	file_munge_filename ($filename, $extensions, $alerts=TRUE)
	file_unmunge_filename ($filename)
	file_create_filename ($basename, $directory)
	file_delete ($path)
	file_space_used ($uid=NULL)
	file_save_upload ($source, $validators=array(), $dest=FALSE, $replace=FILE_EXISTS_RENAME)
	file_validate_name_length ($file)
	file_validate_extensions ($file, $extensions)
	file_validate_size ($file, $file_limit=0, $user_limit=0)
	file_validate_is_image (&$file)
	file_validate_image_resolution (&$file, $maximum_dimensions=0, $minimum_dimensions=0)
	file_save_data ($data, $dest, $replace=FILE_EXISTS_RENAME)
	file_set_status (&$file, $status)
	file_transfer ($source, $headers)
	file_download ()
	file_scan_directory ($dir, $mask, $nomask=array('.', '..', 'CVS'), $callback=0, $recurse=TRUE, $key= 'filename', $min_depth=0, $depth=0)
	file_directory_temp ()
	file_directory_path ()
	file_upload_max_size ()
	file_get_mimetype ($filename, $mapping=NULL)

Detailed Description

Common file handling functions.

Enumeration Type Documentation

enum FILE_STATUS_TEMPORARY

A files status can be one of two values: temporary or permanent. The status for each file Drupal manages is stored in the {files} tables. If the status is temporary Drupal's file garbage collection will delete the file and remove it from the files table after a set period of time.

If you wish to add custom statuses for use by contrib modules please expand as binary flags and consider the first 8 bits reserved. (0,1,2,4,8,16,32,64,128)

Function Documentation

file_check_directory	(	&$	directory,
		$	mode = `0`,
		$	form_item = `NULL`
	)

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.

file_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.

   // Returns FALSE:
   file_check_location('/www/example.com/files/../../../etc/passwd', '/www/example.com/files');

Parameters:

	$source	A string set to the file to check.
	$directory	A string where the file should be located.

Returns:: 0 for invalid path or the real path of the source.

file_check_path ( &$ path )

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.

file_copy	(	&$	source,
		$	dest = `0`,
		$	replace = `FILE_EXISTS_RENAME`
	)

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.

file_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.

Parameters:

	$basename	string filename
	$directory	string directory

Returns:

file_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.

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).

file_create_url ( $ path )

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.

file_delete ( $ path )

Delete a file.

Parameters:

$path

A string containing a file path.

Returns:: TRUE for success, FALSE for failure.

file_destination	(	$	destination,
		$	replace
	)

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.

file_directory_path ( )

Determine the default 'files' directory.

Returns:: A string containing the path to Drupal's 'files' directory.

file_directory_temp ( )

Determine the default temporary directory.

Returns:: A string containing a temp directory.

file_download ( )

Call modules that implement hook_file_download() to find out if a file is accessible and what headers it should be transferred with. If a module returns -1 drupal_access_denied() will be returned. If one or more modules returned headers the download will start with the returned headers. If no modules respond drupal_not_found() will be returned.

file_get_mimetype	(	$	filename,
		$	mapping = `NULL`
	)

Determine an Internet Media Type, or MIME type from a filename.

Parameters:

	$filename	Name of the file, including extension.
	$mapping	An optional array of extension to media type mappings in the form 'extension1\|extension2\|...' => 'type'.

Returns:: The internet media type registered for the extension or application/octet-stream for unknown extensions.

file_move	(	&$	source,
		$	dest = `0`,
		$	replace = `FILE_EXISTS_RENAME`
	)

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.

file_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".

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.

file_save_data	(	$	data,
		$	dest,
		$	replace = `FILE_EXISTS_RENAME`
	)

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 0 on error

file_save_upload	(	$	source,
		$	validators = `array()`,
		$	dest = `FALSE`,
		$	replace = `FILE_EXISTS_RENAME`
	)

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 file object. 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 0 in the event of an error.

file_scan_directory	(	$	dir,
		$	mask,
		$	nomask = `array('.', '..', 'CVS')`,
		$	callback = `0`,
		$	recurse = `TRUE`,
		$	key = `'filename'`,
		$	min_depth = `0`,
		$	depth = `0`
	)

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.

file_set_status	(	&$	file,
		$	status
	)

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.

file_space_used ( $ uid = NULL )

Determine total disk space used by a single user or the whole filesystem.

Parameters:

$uid

An optional user id. A NULL value returns the total space used by all files.

file_transfer	(	$	source,
		$	headers
	)

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.

file_unmunge_filename ( $ filename )

Undo the effect of upload_munge_filename().

Parameters:

$filename

string filename

Returns:: string

file_upload_max_size ( )

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

file_validate_extensions	(	$	file,
		$	extensions
	)

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.

file_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.

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.

file_validate_is_image ( &$ file )

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.

file_validate_name_length ( $ file )

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.

file_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.

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.

File interface

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation