Important Drupal 7 File API Functions

All the File API functions are at http://api.drupal.org/api/drupal/includes--file.inc/7, but it can be hard to sort out which ones you really want to use. Here's a summary:

• file_save_data(): Writes a buffer to a managed file. The file will be named in streams format, as in public://somefile.txt or private://somefile.txt. This returns a file object which can be used in relation to other Drupal APIs. Example: $file_object = file_save_data("This data should go in a file", "public://somefile.txt");
• file_unmanaged_save_data(): Writes a file just like file_save_data(), but nothing is done to the database; the file is not a Drupal object in any way, it's just a file. This function returns the filepath. Example: $filepath = file_unmanaged_save_data("This data should go in a file", "public://somefile.txt");
• file_copy() and file_move(): Take a file object and copy or move to a stream path, returning a file object. Example: $file_object = file_copy($some_file_object, "public://somefile.txt");
• file_unmanaged_copy() and file_unmanaged_move(): Take a stream filepath and copies/moves to another stream filepath, returning a filepath. Example: $filepath = file_unmanaged_copy("private://afile.txt", "public://somefile.txt");
• file_prepare_directory(): Checks, creates, sets permissions on a directory path. Example: $directory = "public://somedir/anotherdir"; $result = file_prepare_directory($directory, FILE_MODIFY_PERMISSIONS | FILE_CREATE_DIRECTORY);. This will attempt to create the directory and set standard permissions on it, returning FALSE if it fails. The $directory must be passed as a variable.
• file_delete(): Delete a file and its associated record in the file_managed table. May return TRUE for success, FALSE for failure, or an array of references to the file that prevented it from being deleted. Example: $result = file_delete($file_object, TRUE);. (Because this example sets the the second parameter $force = TRUE, file_delete will attempt to delete the physical file whether or not other modules had references to it.).
• file_unmanaged_delete() and file_unmanaged_delete_recursive(): Delete a file (or directory tree) from the filesystem. Returns TRUE for success. Examples: $result = file_unmanaged_delete("public://somefile.txt"); or $result = file_unmanaged_delete_recursive("public://somedir");
• file_create_url(): Translate a filepath like public://somefile.txt into an accessible URL like http://example.com/sites/default/files/somefile.txt. Example: $url = file_create_url("public://somefile.txt");

PHP File Functions

The Drupal File API is intended to be the default way to work with files in Drupal, especially files that need to be managed in the database. However the Drupal functions are not intended to completely replace the PHP file functions, so don't forget about PHP functions including file(), to read a file into an array, file_get_contents()/file_put_contents() to read/write from a buffer, fopen()/fread()/fwrite(), is_dir(), is_file((), is_readable(), is_writable(), etc. In many simple cases the Drupal API will provide what's necessary, but the vast majority of the PHP functions work perfectly with streams, so will work with Drupal schemes like public://somefile.txt and private://anotherfile.txt as well as PHP-provided schemes like https://example.com/somefile.html and ftp://ftp@example.com/some/file.txt.

Example Code

The File Example in the Examples Project has a full example implementation of a session:// scheme that writes "files" to the $_SESSION variable.