Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

File API changes from Drupal 6 to Drupal 7

Last updated on
October 14, 2016 - 20:53

There are three key and pervasive things that happened to the File API between Drupal 6 and Drupal 7:

  1. Any API that used to take a traditional filepath like "sites/default/files/something.txt" now must take a stream-oriented file path like "public://something.txt" or "private://something.txt".
  2. Many APIs used to take a string if they were acting on an unmanaged file, or a file object if acting on a managed file. Now those functions have been split out, so we now have file_copy() (which takes a file object) and file_unmanaged_copy() (which takes a stream-oriented filepath like "public://example.txt").
  3. file_create_path() and file_check_directory() were merged into file_prepare_directory().
  4. A smaller item: drupal_realpath() must be used in place of realpath().

Summary of managed/unmanaged File API changes

Drupal 6 Drupal 7 Description
file_copy() file_unmanaged_copy() Copy a file to a new location without saving a record in the database.
n/a file_copy() Copies a file to a new location and adds a file record to the database. Also invokes hook_file_copy() so that other modules may act on the copy action.
file_move() file_unmanaged_move() Move a file to a new location but make no changes to the database.
n/a file_move() Move a file to a new location and update the file's database entry. Also invokes hook_file_move() so that other modules may act on the move action.
file_delete() file_unmanaged_delete() Delete a file.
n/a file_delete() Delete a file and its database record. Also invokes hook_file_delete() to let other modules perform clean-up actions when file is deleted.
file_save_data() file_unmanaged_save_data() Save a string to the specified destination but makes no changes to the database.
n/a file_save_data() Save a string to the specified destination and create a database file entry.
n/a file_load() Load a file object from the database. Also invokes hook_file_load() to allow other modules to do things as the file is loaded.
n/a file_validate() Check that a file meets the criteria specified by the validators. Accepts an associative array of callback functions used to validate the file. Also calls hook_file_validate() to let other modules perform validation on the new file.
n/a file_save() Save a file object to the database. Calls either hook_file_insert() or hook_file_update(), depending on whether a $file->fid is specified.


Drupal 6.x:

file_copy($source, $paths['target'] . $base);
$paths['files'][] = $source;

Drupal 7.x:

$filepath = file_unmanaged_copy($source, $paths['target'] . $base);
$paths['files'][] = $filepath;


Drupal 6.x:


Drupal 7.x:



Drupal 6.x:

if (file_save_data($data, $dest)) {
  $language->javascript = $data_hash;
  $status = ($status == 'deleted') ? 'updated' : 'created';

Drupal 7.x:

if (file_unmanaged_save_data($data, $dest)) {
  $language->javascript = $data_hash;
  $status = ($status == 'deleted') ? 'updated' : 'created';
Drupal 6 Drupal 7 Notes
file_create_path() file_prepare_directory(FILE_CREATE_DIRECTORY)
file_check_directory() file_prepare_directory(FILE_MODIFY_PERMISSIONS) Probably most of the time people who just want to make sure a directory exists and is writable will use file_prepare_directory(FILE_CREATE_DIRECTORY | FILE_MODIFY_PERMISSIONS)

Many other functions used before Drupal 7 will no longer be necessary, as, for example, there is normally no need to check where on the filesystem the "public" file directory is -- you use use the streamwrapper notation and everything is done for you.