MDL-18111 improving file api comments and docs, fixing license header

diff --git a/file.php b/file.php
index 5d04ab11a8d6825ee3d1e78627872b56e0940d9d..c7f1fb8b28ea21c685e2cbd72623c2773009ac98 100644 (file)
--- a/file.php
+++ b/file.php
@@ -1,93 +1,115 @@
-<?php // $Id$
-      // This script fetches files from the dataroot directory
-      //
-      // You should use the get_file_url() function, available in lib/filelib.php, to link to file.php.
-      // This ensures proper formatting and offers useful options.
-      //
-      // Syntax:      file.php/courseid/dir/dir/dir/filename.ext
-      //              file.php/courseid/dir/dir/dir/filename.ext?forcedownload=1 (download instead of inline)
-      //              file.php/courseid/dir (returns index.html from dir)
-      // Workaround:  file.php?file=/courseid/dir/dir/dir/filename.ext
-
-    require_once('config.php');
-    require_once('lib/filelib.php');
-
-    if (!isset($CFG->filelifetime)) {
-        $lifetime = 86400;     // Seconds for files to remain in caches
+<?php
+
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * This script fetches legacy files from the course files in dataroot directory
+ *
+ * You should use the get_file_url() function, available in lib/filelib.php, to link to file.php.
+ * This ensures proper formatting and offers useful options.
+ * Syntax:      file.php/courseid/dir/dir/dir/filename.ext
+ *              file.php/courseid/dir/dir/dir/filename.ext?forcedownload=1 (download instead of inline)
+ *              file.php/courseid/dir (returns index.html from dir)
+ * Workaround:  file.php?file=/courseid/dir/dir/dir/filename.ext
+ *
+ * @package    moodlecore
+ * @subpackage file
+ * @copyright  1999 onwards Martin Dougiamas (http://dougiamas.com)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+require_once('config.php');
+require_once('lib/filelib.php');
+
+if (!isset($CFG->filelifetime)) {
+    $lifetime = 86400;     // Seconds for files to remain in caches
+} else {
+    $lifetime = $CFG->filelifetime;
+}
+
+// disable moodle specific debug messages
+disable_debugging();
+
+$relativepath  = get_file_argument();
+$forcedownload = optional_param('forcedownload', 0, PARAM_BOOL);
+
+// relative path must start with '/', because of backup/restore!!!
+if (!$relativepath) {
+    print_error('invalidargorconf');
+} else if ($relativepath{0} != '/') {
+    print_error('pathdoesnotstartslash');
+}
+
+// extract relative path components
+$args = explode('/', ltrim($relativepath, '/'));
+
+if (count($args) == 0) { // always at least courseid, may search for index.html in course root
+    print_error('invalidarguments');
+}
+
+$courseid = (int)array_shift($args);
+$relativepath = '/'.implode('/', $args);
+
+// security: limit access to existing course subdirectories
+if (!$course = $DB->get_record('course', array('id'=>$courseid))) {
+    print_error('invalidcourseid');
+}
+
+if ($course->id != SITEID) {
+    require_login($course->id, true, null, false);
+
+} else if ($CFG->forcelogin) {
+    if (!empty($CFG->sitepolicy)
+        and ($CFG->sitepolicy == $CFG->wwwroot.'/file.php'.$relativepath
+             or $CFG->sitepolicy == $CFG->wwwroot.'/file.php?file='.$relativepath)) {
+        //do not require login for policy file
     } else {
-        $lifetime = $CFG->filelifetime;
+        require_login(0, true, null, false);
     }
+}
 
-    // disable moodle specific debug messages
-    disable_debugging();
+$context = get_context_instance(CONTEXT_COURSE, $course->id);
 
-    $relativepath = get_file_argument();
-    $forcedownload = optional_param('forcedownload', 0, PARAM_BOOL);
+$fs = get_file_storage();
 
-    // relative path must start with '/', because of backup/restore!!!
-    if (!$relativepath) {
-        print_error('invalidargorconf');
-    } else if ($relativepath{0} != '/') {
-        print_error('pathdoesnotstartslash');
-    }
-
-    // extract relative path components
-    $args = explode('/', ltrim($relativepath, '/'));
-
-    if (count($args) == 0) { // always at least courseid, may search for index.html in course root
-        print_error('invalidarguments');
-    }
+$fullpath = $context->id.'course_content0'.$relativepath;
 
-    $courseid = (int)array_shift($args);
-    $relativepath = '/'.implode('/', $args);
-
-    // security: limit access to existing course subdirectories
-    if (!$course = $DB->get_record('course', array('id'=>$courseid))) {
-        print_error('invalidcourseid');
+if (!$file = $fs->get_file_by_hash(sha1($fullpath))) {
+    if (strrpos($fullpath, '/') !== strlen($fullpath) -1 ) {
+        $fullpath .= '/';
     }
-
-    if ($course->id != SITEID) {
-        require_login($course->id, true, null, false);
-
-    } else if ($CFG->forcelogin) {
-        if (!empty($CFG->sitepolicy)
-            and ($CFG->sitepolicy == $CFG->wwwroot.'/file.php'.$relativepath
-                 or $CFG->sitepolicy == $CFG->wwwroot.'/file.php?file='.$relativepath)) {
-            //do not require login for policy file
-        } else {
-            require_login(0, true, null, false);
-        }
-    }
-
-    $context = get_context_instance(CONTEXT_COURSE, $course->id);
-
-    $fs = get_file_storage();
-
-    $fullpath = $context->id.'course_content0'.$relativepath;
-
-    if (!$file = $fs->get_file_by_hash(sha1($fullpath))) {
-        if (strrpos($fullpath, '/') !== strlen($fullpath) -1 ) {
-            $fullpath .= '/';
-        }
-        if (!$file = $fs->get_file_by_hash(sha1($fullpath.'/.'))) {
-            send_file_not_found();
-        }
+    if (!$file = $fs->get_file_by_hash(sha1($fullpath.'/.'))) {
+        send_file_not_found();
     }
-    // do not serve dirs
-    if ($file->get_filename() == '.') {
-        if (!$file = $fs->get_file_by_hash(sha1($fullpath.'index.html'))) {
-            if (!$file = $fs->get_file_by_hash(sha1($fullpath.'index.htm'))) {
-                if (!$file = $fs->get_file_by_hash(sha1($fullpath.'Default.htm'))) {
-                    send_file_not_found();
-                }
+}
+// do not serve dirs
+if ($file->get_filename() == '.') {
+    if (!$file = $fs->get_file_by_hash(sha1($fullpath.'index.html'))) {
+        if (!$file = $fs->get_file_by_hash(sha1($fullpath.'index.htm'))) {
+            if (!$file = $fs->get_file_by_hash(sha1($fullpath.'Default.htm'))) {
+                send_file_not_found();
             }
         }
     }
+}
 
-    // ========================================
-    // finally send the file
-    // ========================================
-    session_get_instance()->write_close(); // unlock session during fileserving
-    send_stored_file($file, $lifetime, $CFG->filteruploadedfiles, $forcedownload);
+// ========================================
+// finally send the file
+// ========================================
+session_get_instance()->write_close(); // unlock session during fileserving
+send_stored_file($file, $lifetime, $CFG->filteruploadedfiles, $forcedownload);