Moodle 中文 API 之文件管理API

淩亂°似流年 2022-08-06 03:08 306阅读 0赞

# File API  文件管理 #

## 目录 ##

1. 概述

2. 文件域

2.1 命名文件域

3. 提供文件给用户

4. 从用户那获取文件

5. 例子

5.1 浏览文件

5.2 移动文件

5.3 文件列表

5.4创建文件

5.5 读文件

5.6 删除文件

1. 概述

文件 API 是讲述在Moodle中的所有的文件存储. 如果你对文件如何工作感兴趣,请到官网查看[File API internals][File_API_internals]. 这篇文章仅仅是告诉你知道如何使用 file API.与之相关的是[Repository API][Repository_API](让用户从moodle获取文件)

如果你想知道如何管理文件在moodle 表单中, 你最好在去官网阅读 [Using the File API in Moodle forms][Using_the_File_API_in_Moodle_forms].

2. 文件域

文件被保存在file areas. 一个文件域被唯一定义通过如下:

· 一个 context id.

· 完整的component 名字 (使用 [Frankenstyle][]), 例如 'course', 'mod\_forum', 'mod\_glossary', 'block\_html'.

· 一个文件域类型(type), 例如 'intro' 或 'post'.

· 一个唯一的 itemid. 一般的, 这个 itemid 会依赖文件域类型. 例如, 对于 'course', 'intro' 文件域, 那么itemid 就是 0. 对于 forum post, 那就是它的 post id.

文件域并不是分散的到处都是, 它们存储在 files 表里. 请注意每一个子系统只能访问自己的文件域, 例如代码放在 /mod/assignment/\* 只能访问component名为 'mod\_assignment'.的文件。

2.1 命名文件域

文件域的名字不是严格定义的, 但是强烈推荐你使用具有标志意思的名字 如(intro, post, attachment, description, ...).

3. 提供文件给用户

你必须使用包含一个 file-serving 脚本的文件URL , 通常是 pluginfile.php. 例如：一般 URL 的形式像这样：

$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext

特殊一点的可能像这样

$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg

通常你可以使用函数moodle\_url::make\_pluginfile\_url()自动生成URL

$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename());

注意: 如果你不需要 'itemid', 请填入空他将会在 URL中被忽略 - 你必须提供它在提供提供文件的回调函数里.如下

文件服务脚本会查看context id, 和 component 名字, 以及 file area 名字和文件的分配及安全检查.

注意:很多时候, 当开发第三方插件时, pluginfile.php 被看做是一个回调函数在合适的插件里. 这里函数存放在lib.php 文件里 且命名为 component\_name\_pluginfile().这些 arbitrary/extra/infomation.ext 是通过回调生成的. 例如, 文件存在 mod\_forum+post 文件域(file area) 那么为他提供服务的是 mod\_forum\_pluginfile 函数 在 mod/forum/lib.php.这个函数在 MYPLUGIN/lib.php 中通常会成对出现像下面的例子, 具体访问权限还要依赖插件所处的位置 (例如. assignment 文件只能让老师访问学生提交的文件, forum attachments 需要通过discussion 提交上来的文件):

你经常会用一个 API 去自动生成URL, 经常file\_rewrite\_pluginfile\_urls函数.

3. 从用户那获取文件

在官网上查看 [Using the File API in Moodle forms][Using_the_File_API_in_Moodle_forms]

5. 例子

远离核心代码的开发并不真正使用文件API，而是使用formslib代替他们自动完成.

5.1 浏览文件

$browser = get_file_browser();
    $context = get_system_context();
     
    $filearea = null;
    $itemid   = null;
    $filename = null;
    if ($fileinfo = $browser->get_file_info($context, $component, $filearea, $itemid, '/', $filename)) {
        // 建立一个面包屑
        $level = $fileinfo->get_parent();
        while ($level) {
            $path[] = array('name'=>$level->get_visible_name());
            $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();
                // 显示 contextid, itemid, component, filepath 和 filename
                var_dump($child->get_params());
            }
        }
    }

5.2 移动文件

例如, 如果你仅仅建立一个文件在临时路径里

$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
             '/' . $preferences->backup_name;

而且你想将他移动到course\_backup 文件域, 那么你需要需做

$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
     $fs = get_file_storage();
     $file_record = array('contextid'=>$context->id, 'component'=>'course', 'filearea'=>'backup',
             'itemid'=>0, 'filepath'=>'/', 'filename'=>$preferences->backup_name,
             'timecreated'=>time(), 'timemodified'=>time());
     $fs->create_file_from_pathname($file_record, $from_zip_file);

5.3 文件列表

$fs = get_file_storage();
    $files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
    foreach ($files as $f) {
        // $f 是stored_file的一个实例
        echo $f->get_filename();
    }

或者像链接...

$out = array();
     
    $fs = get_file_storage();
    $files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
     
    foreach ($files as $file) {
        $filename = $file->get_filename();
        $url = moodle_url::make_file_url('/pluginfile.php', array($file->get_contextid(), 'mod_assignment', 'submission',
                $file->get_itemid(), $file->get_filepath(), $filename));
        $out[] = html_writer::link($url, $filename);
    }
    $br = html_writer::empty_tag('br');
     
    return implode($br, $out);

5.4 创建文件

这儿介绍了如何创建一个文本字符串文件. 相当于 PHP 函数file\_put\_contents.

$fs = get_file_storage();
     
    // 准备文件记录对象
    $fileinfo = array(
        'contextid' => $context->id, // context的ID
        'component' => 'mod_mymodule',     // 模块名
        'filearea' => 'myarea',     // 文件域
        'itemid' => 0,               // usually = ID of row in table
        'filepath' => '/',           // 文件路径的开始和结束使用 /
        'filename' => 'myfile.txt'); // 文件名
     
    // 创建包含文本'hello world'的文件
    $fs->create_file_from_string($fileinfo, 'hello world');

如果你想创建一个文件在Moodle file area中基于一个真的文件，如.临时的目录中,你能用create\_file\_from\_pathname代替. 类似的,你能创建一个其他已经存在于 Moodle的本地文件通过使用 create\_file\_from\_storedfile. 浏览通过lib/filestorage/file\_storage.php 获取具体信息.

不同与普通文件, 这个方法不会自动重写一个存在的文件. 如果你希望重写一个文件, 你首先得获取这个文件删除它 (如果它存在的话),然后再次创建他.

5.5 读文件

这是读文件的一种方式, 等价于file\_get\_contents.请注意你仅仅被允许访问来自 mod/mymodule/\* 模块的代码, 他是不能在其他任何地方访问的. 其他代码不得不使用 file\_browser接口代替.

$fs = get_file_storage();
     
    // Prepare file record object
    $fileinfo = array(
        'component' => 'mod_mymodule',     // usually = table name
        'filearea' => 'myarea',     // 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
     
    // 获取
    $file = $fs->get_file($fileinfo['contextid'], $fileinfo['component'], $fileinfo['filearea'],
                          $fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename']);
     
    // 读取内容
    if ($file) {
        $contents = $file->get_content();
    } else {
        // 文件不存在时 代码
    }

如果你想直接从硬盘访问这个文件, 他是禁止的.你可以在临时目录中得导一份拷贝.像这样 $file->copy\_content\_to($pathname)，然后就可以访问了.

5.6 删除文件

$fs = get_file_storage();
     
    // 准备文件记录对象
    $fileinfo = array(
        'component' => 'mod_mymodule',
        'filearea' => 'myarea',     // 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'); // 文件名
     
    // 获取文件
    $file = $fs->get_file($fileinfo['contextid'], $fileinfo['component'], $fileinfo['filearea'], 
            $fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename']);
     
    // 如果存在删除它
    if ($file) {
        $file->delete();
    }

[File_API_internals]: https://docs.moodle.org/dev/File_API_internals
[Repository_API]: https://docs.moodle.org/dev/Repository_API
[Using_the_File_API_in_Moodle_forms]: https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms
[Frankenstyle]: https://docs.moodle.org/dev/Frankenstyle