File API changes from Drupal 6 to Drupal 7
Last updated on
14 October 2016
Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites
There are three key and pervasive things that happened to the File API between Drupal 6 and Drupal 7:
- 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".
- 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").
- file_create_path() and file_check_directory() were merged into file_prepare_directory().
- 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. |
file_copy()
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;
file_delete()
Drupal 6.x:
file_delete($file_path);
Drupal 7.x:
file_unmanaged_delete($file_path);
file_save_data()
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.
Help improve this page
Page status: No known problems
You can:
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion