View source for Development:Using the File API

{{Moodle 2.0}}
The File API is for managing all the files stored by Moodle. If you are interested in how the file API works internally, see [[Development:File API]]. The page is just about what you need to know to use the file API. Related is the [[Development:Repository API]], which lets users get files into Moodle.

If you are looking for an explanation on how to upgrade pre-2.0 code to using the file API, you most likely need to read [[Development:Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]].

==File areas==

Files are conceptually stored in '''file areas'''. A file area is uniquely identified by:
* A context id.
* A file area type, for example 'course_intro' or 'forum_post'.
* A unique itemid. Normally, the itemid relates to something depending on the file area type. For example, for a 'course_intro' file area, the itemid is is the course id. For forum post, it is the post id.

File areas are not listed separately anywhere, they are stored implicitly in the files table. Please note that each subsystem is allowed to access only own file areas, for example core code must not access module or block files directly.

===Naming file areas===

It is important that file areas are named consistently so we do not get name collisions, and so the names are easy to understand. Please follow the following guidelines:

====start of the name====

If the file area belongs to a plugin, please use the plugin name as the start of the file area name.

This is the same plugin name that you would use for get_string calls. Some examples:
* All file areas that belong to the forum modules should have a name beginning with 'forum'. For example 'forum_post', 'forum_intro'.
* A file area belonging to the HTML block would start 'block_html_'.
* A file area belonging to a question type would start 'qtype_myqtype_', except this is probably not necessary, because question type images should probably be stored in the core 'question_text' file area.
* If the file area is used by a local hack, the file area name should start 'local_'.

If the file area belongs to core code, the file area name should start with a prefix that indicates what part of Moodle it belongs to.

But try to avoid clashing with prefixes that a plugin might use. Some examples:
* 'course_intro'
* 'question_text'
* 'user_draft' (although draft file areas are a special case).

====rest of the name====

Like naming variables or functions, try to find a name that is short, but says exactly what the file area is for.

If possible use the name of the file area to give a clue as to which database table the itemid relates to. For example:

* For the 'forum_post' file area, the itemid links to forum_post.id.
* For 'question_text' file area, the itemid links to question.id. (Would it be permissible to call this file area just question?)

==Serving files to users==

You must refer to the file with a URL that includes a file-serving script, often pluginfile.php. For example

The general form of the URL is something like
<code php>
$url = $CFG->wwwroot/pluginfile.php/$contextid/$filearea/arbitrary/extra/infomation.ext
</code>

A specific example might be
<code php>
$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/forum_post/$postid/image.jpg
</code>

The file serving script then looks at the context id, and the file area name, and based on that arranges for the file to be served, following appropriate security checks.

Often, this is done by calling a callback function in the appropriate plugin. The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the forum_post file area end up being served by the forum_pluginfile function in mod/forum/lib.php.

You normally use an API function to generate these URL automatically, most often the file_rewrite_pluginfile_urls function.

==Getting files from the user==

* See [[Development:Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]]
==Examples==
Please note that in reality developers outside of core will not deal with file api directly in majority of cases, instead use formslib elements which are doing all this automatically.

===Browsing files===
<code php>
$browser = get_file_browser();
$context = get_system_context();

$filearea = null;
$itemid   = null;
$filename = null;
if ($fileinfo = $browser->get_file_info($context, $filearea, $itemid, '/', $filename)) {
    // build a Breadcrumb trail
    $level = $fileinfo->get_parent();
    while ($level) {
        $params = base64_encode(serialize($level->get_params()));
        $path[] = array('name'=>$level->get_visible_name(), 'path'=>$params);
        $level = $level->get_parent();
    }
    $path = array_reverse($path);
    $children = $fileinfo->get_children();
    foreach ($children as $child) {
        if ($child->is_directory()) {
            echo $child->get_visible_name();
            // display contextid, itemid, filepath and filename
            var_dump($child->get_params());
        }
    }
}

</code>
===Moving files around===

For example, if you have just built a file at the path
<code php>
 $from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
         '/' . $preferences->backup_name;
</code>
And you want to move it into the course_backup file area, do
<code php>
 $context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
 $fs = get_file_storage();
 $file_record = array('contextid'=>$context->id, 'filearea'=>'course_backup',
         'itemid'=>0, 'filepath'=>'/', 'filename'=>$preferences->backup_name,
         'timecreated'=>time(), 'timemodified'=>time());
 $fs->create_file_from_pathname($file_record, $from_zip_file);
</code>
===Create a copy of stored file===
If you need to create a copy of stored file (actually, it add a new record in database):
<code php>
$context  = get_context_instance_by_id($contextid);
$file_info = $browser->get_file_info($context, $filearea, $fileitemid, $filepath, $filename);
// copy this file to draft area
$file_info->copy_to_storage($user_context->id, 'user_draft', $newitemid, '/', $title);
</code>

The above code is intended for user-interface behaviour which respects the current user's permissions. If you need to write code which copies files at the back-end in areas which are not directly editable by users (for example, when copying a glossary entry to another glossary, and you want to copy its attachments), you do not need to use the user-level $browser at all. All operations are carried out with the file_storage object (usually $fs). The method to use is create_file_from_storedfile.

For example, the glossary stores per-entry files in two areas ('glossary_attachment' which stores attachments and 'glossary_entry' which stores files directly related to the HTML definition, such as embedded images). The following code copies all the files relating to a specific glossary entry from one such area to a different glossary item in a different glossary. Note that it changes the context ID and item ID of each file to represent the new context (for the different glossary module) and the new glossary entry (a new row was added to glossary_entries).

<code php>
$fs = get_file_storage();
if ($files = $fs->get_area_files($oldcontextid, 'glossary_attachment', $oldentryid)) {
    foreach ($files as $file) {
        $fs->create_file_from_storedfile(array(
                'contextid' => $newcontextid,
                'itemid' => $newentryid), $file);
    }
}
</code>

=== List area files ===
<code php>
$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'user_draft');
foreach ($files as $f) {
    // $f is an instance of stored_file
    echo $f->get_filename();
}
</code>

=== Create file ===

Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function file_put_contents.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
    'filearea' => 'my_area';     // usually = table name
    'itemid' => 0;               // usually = ID of row in table
    'contextid' => $context->id; // ID of context
    'filepath' => '/';           // any path beginning and ending in /
    'filename' => 'myfile.txt'); // any filename

// Create file containing text 'hello world'
$fs->create_file_from_string($fileinfo, 'hello world');
</code>

If you want to create a file in the Moodle file area based on a 'real' file e.g. in a temporary folder, you can use <tt>create_file_from_pathname</tt> instead.

Unlike with ordinary files, this method will not automatically overwrite an existing file. If you wish to overwrite a file, you must get the file and (if it exists) delete it.

=== Read file ===

This is a way to read a file, equivalent to <tt>file_get_contents</tt>.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
    'filearea' => 'my_area';     // usually = table name
    'itemid' => 0;               // usually = ID of row in table
    'contextid' => $context->id; // ID of context
    'filepath' => '/';           // any path beginning and ending in /
    'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo->contextid, $fileinfo->filearea, 
        $fileinfo->itemid, $fileinfo->filepath, $fileinfo->filename);

// Read contents
if ($file) {
    $contents = $file->get_content();
} else {
    // file doesn't exist - do something
}
</code>

If you want to access the file directly on disk, this is not permitted. Instead, you need to make a copy of the file in a temporary area and use that. You can do this with <tt>$file->copy_content_to($pathname)</tt>.

=== Delete file ===

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
    'filearea' => 'my_area';     // usually = table name
    'itemid' => 0;               // usually = ID of row in table
    'contextid' => $context->id; // ID of context
    'filepath' => '/';           // any path beginning and ending in /
    'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo->contextid, $fileinfo->filearea, 
        $fileinfo->itemid, $fileinfo->filepath, $fileinfo->filename);

// Delete it if it exists
if ($file) {
    $file->delete();
}
</code>

==See also==

* [[Development:File API]] how the File API works internally.
* [[Roadmap|Moodle 2.0 roadmap]]

[[Category:Developer]]
[[Category:Files]]