7.x file.inc file_usage_add(stdClass $file, $module, $type, $id, $count = 1)

Records that a module is using a file.

This usage information will be queried during file_delete() to ensure that a file is not in use before it is physically removed from disk.

Examples:

  • A module that associates files with nodes, so $type would be 'node' and $id would be the node's nid. Files for all revisions are stored within a single nid.
  • The User module associates an image with a user, so $type would be 'user' and the $id would be the user's uid.

Parameters

$file: A file object.

$module: The name of the module using the file.

$type: The type of the object that contains the referenced file.

$id: The unique, numeric ID of the object containing the referenced file.

$count: (optional) The number of references to add to the object. Defaults to 1.

See also

file_usage_list()

file_usage_delete()

Related topics

9 calls to file_usage_add()
FileDeleteTest::testInUse in modules/simpletest/tests/file.test
Tries deleting a file that is in use.
FileUsageTest::testAddUsage in modules/simpletest/tests/file.test
Tests file_usage_add().
file_field_insert in modules/file/file.field.inc
Implements hook_field_insert().
file_field_update in modules/file/file.field.inc
Implements hook_field_update().
image_field_update_field in modules/image/image.module
Implements hook_field_update_field().

... See full list

File

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

Code

function file_usage_add(stdClass $file, $module, $type, $id, $count = 1) {
  db_merge('file_usage')
    ->key(array(
      'fid' => $file->fid,
      'module' => $module,
      'type' => $type,
      'id' => $id,
    ))
    ->fields(array('count' => $count))
    ->expression('count', 'count + :count', array(':count' => $count))
    ->execute();
}

Comments

texas-bronius’s picture

At a glance, it looks like one doesn't need to do a file_load in the event that you do not already have your file object loaded. Just

$fid = NNN;
$file = new stdClass();
$file->fid = $fid;
file_usage_add($file, 'file', 'node', $node->nid);
TajinderSingh’s picture

$type just needs to be something unique within your module's types of file usage. The value of the string itself is arbitrary.

So if you have a module which stores pictures of cats and dogs, and you want to address those two different types of usage separately, you might use (contrived examples obviously):

$cat = MYMODULE_load_cat('whiskers');
file_usage_add($file, 'MYMODULE', 'cat_pictures', $cat->id);

$dog = MYMODULE_load_dog('fido');
file_usage_add($file, 'MYMODULE', 'dog_pictures', $dog->id);

But the $type for those could just as easily be cat_foo and dog_foo, all that matters is that you (the module developer) know what they are, so they can be used appropriately with file_usage_delete().

(Note: Was confused, so found via Google at: http://drupal.stackexchange.com/a/116051)

eugenesia’s picture

The $type string parameter affects the links on the File Usage Page listing the uses of the file. The file's File Usage Page is found at file/[fid]/edit, and can be reached via admin/content/file.

If $type is set to 'node', 'user' or a known Drupal entity type, there will be a link to the page of the respective node or user using the file, e.g. with URI node/[nid] or user/[uid].

If $type is set to an arbitrary string such as 'cat_pictures' as mentioned by @TajinderSingh above, there will be no link as Drupal doesn't know how to generate a link to a non-Drupal entity.

The File Usage Page content is generated by the contrib module File Entity, by the function file_entity_usage_page().

When creating the File Usage Page content, Drupal first tries to get info about the entity type via entity_get_info(). This will fail if the $type parameter is set to the name of a non-Drupal entity such as 'cat_pictures'. If so, it will not run entity_uri() to generate a link to the entity's page.