File interface

You are here

  1. 7 includes/ file
  2. 4.6 includes/ file
  3. 4.7 includes/ file
  4. 5 includes/ file
  5. 6 includes/ file
  6. 8 core/includes/ file

Common file handling functions.

Fields on the file object:

  • fid: File ID
  • uid: The {users}.uid of the user who is associated with the file.
  • filename: Name of the file with no path components. This may differ from the basename of the filepath if the file is renamed to avoid overwriting an existing file.
  • uri: URI of the file.
  • filemime: The file's MIME type.
  • filesize: The size of the file in bytes.
  • status: A bitmapped field indicating the status of the file. The first 8 bits are reserved for Drupal core. The least significant bit indicates temporary (0) or permanent (1). Temporary files older than DRUPAL_MAXIMUM_TEMP_FILE_AGE will be removed during cron runs.
  • timestamp: UNIX timestamp for the date the file was added to the database.


Namesort descending Location Description
drupal_basename includes/ Gets the filename from a given path.
drupal_chmod includes/ Sets the permissions on a file or directory.
drupal_dirname includes/ Gets the name of the directory from a given path.
drupal_mkdir includes/ Creates a directory using Drupal's default mode.
drupal_move_uploaded_file includes/ Moves an uploaded file to a new location.
drupal_realpath includes/ Resolves the absolute filepath of a local URI or filepath.
drupal_rmdir includes/ Removes a directory.
drupal_tempnam includes/ Creates a file with a unique filename in the specified directory.
drupal_unlink includes/ Deletes a file.
file_build_uri includes/ Constructs a URI to Drupal's default files location given a relative path.
file_copy includes/ Copies a file to a new location and adds a file record to the database.
file_create_filename includes/ Creates a full file path from a directory and filename.
file_create_htaccess includes/ Creates a .htaccess file in the given directory.
file_create_url includes/ Creates a web-accessible URL for a stream to an external or local file.
file_default_scheme includes/ Gets the default file stream implementation.
file_delete includes/ Deletes a file and its database record.
file_destination includes/ Determines the destination path for a file.
file_directory_temp includes/ Gets the path of system-appropriate temporary directory.
file_download includes/ Menu handler for private file transfers.
file_ensure_htaccess includes/ Creates a .htaccess file in each Drupal files directory if it is missing.
file_get_content_headers includes/ Examines a file object and returns appropriate content headers for download.
file_get_mimetype includes/ Determines an Internet Media Type or MIME type from a filename.
file_get_stream_wrappers includes/ Provides Drupal stream wrapper registry.
file_htaccess_lines includes/ Returns the standard .htaccess lines that Drupal writes to file directories.
file_load includes/ Loads a single file object from the database.
file_load_multiple includes/ Loads file objects from the database.
file_move includes/ Moves a file to a new location and update the file's database entry.
file_munge_filename includes/ Modifies a filename as needed for security purposes.
file_prepare_directory includes/ Checks that the directory exists and is writable.
file_save includes/ Saves a file object to the database.
file_save_data includes/ Saves a file to the specified destination and creates a database entry.
file_save_upload includes/ Saves a file upload to a new location.
file_scan_directory includes/ Finds all files that match a given mask in a given directory.
file_space_used includes/ Determines total disk space used by a single user or the whole filesystem.
file_stream_wrapper_get_class includes/ Returns the stream wrapper class name for a given scheme.
file_stream_wrapper_get_instance_by_scheme includes/ Returns a reference to the stream wrapper class responsible for a scheme.
file_stream_wrapper_get_instance_by_uri includes/ Returns a reference to the stream wrapper class responsible for a given URI.
file_stream_wrapper_uri_normalize includes/ Normalizes a URI by making it syntactically correct.
file_stream_wrapper_valid_scheme includes/ Checks that the scheme of a stream URI is valid.
file_transfer includes/ Transfers a file to the client using HTTP.
file_unmanaged_copy includes/ Copies a file to a new location without invoking the file API.
file_unmanaged_delete includes/ Deletes a file without database changes or hook invocations.
file_unmanaged_delete_recursive includes/ Deletes all files and directories in the specified filepath recursively.
file_unmanaged_move includes/ Moves a file to a new location without database changes or hook invocation.
file_unmanaged_save_data includes/ Saves a string to the specified destination without invoking file API.
file_unmunge_filename includes/ Undoes the effect of file_munge_filename().
file_upload_max_size includes/ Determines the maximum file upload size by querying the PHP settings.
file_uri_scheme includes/ Returns the scheme of a URI (e.g. a stream).
file_uri_target includes/ Returns the part of a URI after the schema.
file_usage_add includes/ Records that a module is using a file.
file_usage_delete includes/ Removes a record to indicate that a module is no longer using a file.
file_usage_list includes/ Determines where a file is used.
file_validate includes/ Checks that a file meets the criteria specified by the validators.
file_validate_extensions includes/ Checks that the filename ends with an allowed extension.
file_validate_image_resolution includes/ Verifies that image dimensions are within the specified maximum and minimum.
file_validate_is_image includes/ Checks that the file is recognized by image_get_info() as an image.
file_validate_name_length includes/ Checks for files with names longer than we can store in the database.
file_validate_size includes/ Checks that the file's size is below certain limits.
file_valid_uri includes/ Determines whether the URI has a valid scheme for file API operations.


Namesort descending Location Description
FILE_CREATE_DIRECTORY includes/ Flag used by file_prepare_directory() -- create directory if not present.
FILE_EXISTS_ERROR includes/ Flag for dealing with existing files: Do nothing and return FALSE.
FILE_EXISTS_RENAME includes/ Flag for dealing with existing files: Appends number until name is unique.
FILE_EXISTS_REPLACE includes/ Flag for dealing with existing files: Replace the existing file.
FILE_MODIFY_PERMISSIONS includes/ Flag used by file_prepare_directory() -- file permissions may be changed.
FILE_STATUS_PERMANENT includes/ Indicates that the file is permanent and should not be deleted.


includes/, line 17
API for handling file uploads and server file management.


Looking to go from a file uri to a file object without reading the files table yourself with SQL? Try file_uri_to_object from the media.module! Oh yes!

This function doesn't exist in drupal 7 core

It's now located in the file_entity module.

I couldn't find any documentation about this anywhere so here's what I did:

* Implementation of hook_form_FORM_ID_alter
hook_form_FORM_ID_alter(&$form, &$form_state, $form_id){

$form['field_MY_FILE_FIELD_NAME']['und'][0]['#process'][] = 'my_processing_function';


* My Ajax Upload File Processing Function
function my_processing_function($element, &$form_state){

// check to see if it's submitted and if there's a file
if ($form_state['submitted'] && $element['#value']['fid']){


// Do stuff to the file here
$fid = $element['#value']['fid']

// make sure we return the element when we're done
return $element;

Here is information on how to save a file that has been uploaded using a form and the type managed_file. The file is normally saved only temporarily and will be deleted automatically during CRON runs.

The form code looks something like this,

function MYMODULE_form ($form, &$form_state){
$form['MY_IMAGE_NAME'] = array(
'#title' => t('My Image'),
'#type' => 'managed_file',
'#description' => t('Please upload an image!'),
'#default_value' => variable_get('MY_IMAGE_NAME', ''),
'#progress_indicator' => 'bar',
'#upload_location' => 'public://',


MYMODULE_form_submit ($form, &$form_state) {
/*Update the status to permanent*/
$form['MY_IMAGE_NAME']['#file']->status = FILE_STATUS_PERMANENT;
/*Save the updated file information to the database*/

You can check that the file is permanent by looking in the "file_managed" table in the "status" field. 0 means temporary, 1 means permanent.

I hope this helps someone. It was a little tricky for me to figure out.

I'm assuming that we're talking about D7 here..........

(If not, please disregard)

How are you getting the form_submit to trigger?

Since the file upload widget submits via ajax, I don't think it's getting called.


You are not crazy

use the form id and submit hook to set up the submit callback, then include the #submit property in the managed file form element. The file uploads according to the callback statements. I have not figured out how to apply the function to a form with multiple upload fields.


Since $form is passed by value, it is my understanding that changing its value in the submit function will not remain once the submit function ends...did this actually work for you?

I have a content type with some file fields
When I insert the content for the first time I know that all the files are new in hook_node_insert

But in hook_node_update how to know if this is new uploaded file when updated the content or the files has not been changed?

How can I change the location of where the uploaded files are saved in my submit function?

I configured the cck file field in my content type to upload to private and currently Drupal is saving it in private://<uid>/. However, I want the upload file to go to private://<uid>/<id>/<subdirectory>/ where and are generated in the submit function. I tried:

        $files = $form_state['values'][$field_name][LANGUAGE_NONE];
        foreach ( $files as $file )
            $file_obj = file_load ( $file['fid'] );
            if ( $file_obj )
                $file_obj->status = FILE_STATUS_PERMANENT;
                $file_obj->uri = $directory . "/" . $file_obj->filename;
                file_save ( $file_obj );

But that didn't work, I kept getting:
"The file used in the Plots field may not be referenced.
Warning: filesize() [function.filesize]: stat failed for private://2/pp/plots/volcano_1.0mpa.png in file_save() (line 570 of /projects/sysint/web_db/servers/drupal/drupal-7.19/includes/"

All help is appreciated.

Actually i m getting some problem in displaying the information which has been filled in the form by the user... And i wanted to show only some of the information in the main e-mail message and so on..... so would you please give me some information regarding to it....

How to use "define('FILE_EXISTS_REPLACE', 1)" in code ..?

I want to replace a file including the database entry into a given fid ..
Can you help me by sample snippets of code ..

It would be useful to have a function in the File API to return a file schema's base URL, as it seems to be hardcoded for example for private schema - currently '/system/files/'.