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

diff --git a/lib/file/file_browser.php b/lib/file/file_browser.php
index 31c8b8454f2094eb4da611dbb2837892df35bf9b..e446e411656367ea6362e9c5fde175fae6d41f5a 100644 (file)
--- a/lib/file/file_browser.php
+++ b/lib/file/file_browser.php
@@ -1,4 +1,28 @@
-<?php  //$Id$
+<?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/>.
+
+
+/**
+ * Utility class for browsing of files.
+ *
+ * @package   moodle-core
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 require_once("$CFG->libdir/file/file_info.php");
 require_once("$CFG->libdir/file/file_info_module.php");
@@ -21,11 +45,16 @@ require_once("$CFG->libdir/file/virtual_root_file.php");
  * file areas, and a file area contains folders and files. The various file_info
  * subclasses return info about the things in this tree. They should be obtained
  * from an instance of this class.
+ *
+ * This virtual tree is different for each user depending of his/her current permissions.
+ * Some branches such as draft areas are hidden, but accessible.
+ *
+ * Always use this abstraction when you need to access module files from core code.
  */
 class file_browser {
 
     /**
-     * Looks up file_info object
+     * Looks up file_info instance
      * @param object $context
      * @param string $filearea
      * @param int $itemid
@@ -50,36 +79,6 @@ class file_browser {
         return null;
     }
 
-    /**
-     * Returns content of local directory
-     */
-    public function build_stored_file_children($context, $filearea, $itemid, $filepath, $urlbase, $topvisiblename, $itemidused, $readaccess, $writeaccess) {
-        $result = array();
-        $fs = get_file_storage();
-
-        $storedfiles = $fs->get_directory_files($context->id, $filearea, $itemid, $filepath, false, true, "filepath, filename");
-        foreach ($storedfiles as $file) {
-            $result[] = new file_info_stored($this, $context, $file, $urlbase, $topvisiblename, $itemidused, $readaccess, $writeaccess, false);
-        }
-
-        return $result;
-    }
-
-    /**
-     * Returns content of coursefiles directory
-     */
-    public function build_coursefile_children($context, $filepath) {
-        $result = array();
-        $fs = get_file_storage();
-
-        $storedfiles = $fs->get_directory_files($context->id, 'course_content', 0, $filepath, false, true, "filepath, filename");
-        foreach ($storedfiles as $file) {
-            $result[] = new file_info_coursefile($this, $context, $file);
-        }
-
-        return $result;
-    }
-
     public function encodepath($urlbase, $path, $forcedownload=false, $https=false) {
         global $CFG;
 

diff --git a/lib/file/file_info_coursefile.php b/lib/file/file_info_coursefile.php
index 9e07380f1ebabe37a56fce95d461ed7f081c84d2..a903a15f12d97d46815cf1cc0042235763a58290 100644 (file)
--- a/lib/file/file_info_coursefile.php
+++ b/lib/file/file_info_coursefile.php
@@ -1,4 +1,28 @@
-<?php  //$Id$
+<?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/>.
+
+
+/**
+ * Class for browsing of legacy course files.
+ *
+ * @package   moodle-core
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 /**
  * Subclass of file_info_stored for files in the course files area.
@@ -34,8 +58,15 @@ class file_info_coursefile extends file_info_stored {
         if (!$this->lf->is_directory()) {
             return array();
         }
-        return $this->browser->build_coursefile_children($this->context, $this->lf->get_filepath());
-    }
 
+        $result = array();
+        $fs = get_file_storage();
+
+        $storedfiles = $fs->get_directory_files($this->context->id, 'course_content', 0, $this->lf->get_filepath(), false, true, "filepath, filename");
+        foreach ($storedfiles as $file) {
+            $result[] = new file_info_coursefile($this->browser, $this->context, $file);
+        }
 
+        return $result;
+    }
 }

diff --git a/lib/file/file_info_stored.php b/lib/file/file_info_stored.php
index 316eadfedebf93ed951a50c6e272d8a1d72a7235..ce1d2db81aeacd563c7f80ac8308e139df09edfa 100644 (file)
--- a/lib/file/file_info_stored.php
+++ b/lib/file/file_info_stored.php
@@ -1,4 +1,28 @@
-<?php  //$Id$
+<?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/>.
+
+
+/**
+ * Utility class for browsing of stored files.
+ *
+ * @package   moodle-core
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 /**
  * Represents an actual file or folder - a row in the file table -
@@ -111,9 +135,18 @@ class file_info_stored extends file_info {
         if (!$this->lf->is_directory()) {
             return array();
         }
-        return $this->browser->build_stored_file_children($this->context, $this->lf->get_filearea(), $this->lf->get_itemid(), $this->lf->get_filepath(),
-                                                          $this->urlbase, $this->topvisiblename, $this->itemidused, $this->readaccess, $this->writeaccess,
-                                                          $this->areaonly);
+
+        $result = array();
+        $fs = get_file_storage();
+
+        $storedfiles = $fs->get_directory_files($this->context->id, $this->lf->get_filearea(), $this->lf->get_itemid(),
+                                                $this->lf->get_filepath(), false, true, "filepath, filename");
+        foreach ($storedfiles as $file) {
+            $result[] = new file_info_stored($this->browser, $this->context, $file, $this->urlbase, $this->topvisiblename,
+                                             $this->itemidused, $this->readaccess, $this->writeaccess, false);
+        }
+
+        return $result;
     }
 
     public function get_parent() {