MDL-32941 parameters moved on top level, little performance improvement, filter and format the description, browse all sub categories level and adjust checks

course/externallib.php

@@ -254,70 +254,117 @@ class core_course_external extends external_api {
      * @return external_function_parameters
      * @since Moodle 2.2
      */
-    public static function get_courses_parameters() {
+    public static function get_categories_parameters() {
         return new external_function_parameters(
-                array('options' => new external_single_structure(
+            array(
-                            array('ids' => new external_multiple_structure(
+                    'categoryid' => new external_value(PARAM_INT, 'category id to be returned - if 0 all the categories that the user can see are returned.', VALUE_DEFAULT, 0),
-                                        new external_value(PARAM_INT, 'Course id')
+                    'addsubcategories' => new external_value(PARAM_BOOL, 'return the sub categories infos
-                                        , 'List of course id. If empty return all courses
+                                                        (1 - default) otherwise only the category info (0)', VALUE_DEFAULT, 1)
-                                            except front page course.',
-                                        VALUE_OPTIONAL)
-                            ), 'options - operator OR is used', VALUE_DEFAULT, array())
                 )
         );
     }
 
     /**
      * Get categories
-    * @param $categoryid the category id to get
+     *
-    * @param $nosubcategories obtain only the category or its subcategories
+     * @param int $categoryid the category id to get - if 0 all categories that the user can see are returned
-    * @return array
+     * @param boolean $addsubcategories obtain only the category (false) or its subcategories (true - default)
+     * @return array list of categories
+     * @since Moodle 2.3
      */
-    public static function get_categories($options) {
+    public static function get_categories($categoryid = 0, $addsubcategories = true) {
         global $CFG, $DB;
         require_once($CFG->dirroot . "/course/lib.php");
-        //validate parameters
-        $params = self::validate_parameters(self::get_categories_parameters(), array('options' => $options));
 
-        $categoryid = $params['options']['categoryid'];
+        // Validate parameters
-        $nosubcats = $params['options']['nosubcategories'];
+        $params = self::validate_parameters(self::get_categories_parameters(),
+                array('categoryid' => $categoryid, 'addsubcategories' => $addsubcategories));
 
-        if (!empty($categoryid)) {
+        // Retrieve the categories
-            $categories = $DB->get_records('course_categories', array('id' => $categoryid));
+        $categories = array();
-            if (!$nosubcats) {
+        if (!empty($params['categoryid'])) {
-                $subcats = $DB->get_records('course_categories', array('parent' => $categoryid));
+            // Retrieve the specified category
-                $categories = array_merge($categories, $subcats);
+            $category = $DB->get_record('course_categories', array('id' => $params['categoryid']));
+            $categories[] = $category;
+
+            // Retrieve its sub subcategories (all levels)
+            if (!empty($addsubcategories)) {
+                $sqllike = $DB->sql_like('path', ':path');
+                $sqlparams = array('path' => $category->path.'/%'); // It will include the specified category
+                $subcategories = $DB->get_records_select('course_categories', $sqllike, $sqlparams, 'path');
+                $categories = array_merge($categories, $subcategories); // Both arrays have integer as keys  
             }          
-        }
+        } else {
-        else {
+            // Retrieve all categories in the database
             $categories = $DB->get_records('course_categories');
         }
 
+        // The not returned categories. key => category id, value => reason of exclusion
+        $excludedcats = array();
+
+        // The returned categories
         $categoriesinfo = array();
+
         foreach ($categories as $category) {
 
-            //security checks
+            // Check if the category is a child of an excluded category, if yes exclude it too (excluded => do not return)
+            $parents = explode('/', $category->path);
+            unset($parents[0]); // First key is always empty because path start with / => /1/2/4
+            foreach ($parents as $parentid) {
+                // Note: when the parent exclusion was due to the context,
+                //       the sub category could still be returned.
+                if (isset($excludedcats[$parentid]) and $excludedcats[$parentid] != 'context') {
+                    $excludedcats[$category->id] = 'parent';
+                }
+            }
+
+            // Check category depth is <= maxdepth (do not check for user who can manage categories)
+            if ((!empty($CFG->maxcategorydepth) && count($parents) > $CFG->maxcategorydepth)
+                    and !has_capability('moodle/category:manage', $context)) {
+                $excludedcats[$category->id] = 'depth';
+            }
+
+            // Check the user can use the category context
             $context = context_coursecat::instance($category->id);
             try {
                 self::validate_context($context);
             } catch (Exception $e) {
+                $excludedcats[$category->id] = 'context';
+
+                // If it was the requested category then throw an exception
+                if (isset($params['categoryid']) && $category->id == $params['categoryid']) {
                     $exceptionparam = new stdClass();
                     $exceptionparam->message = $e->getMessage();
                     $exceptionparam->catid = $category->id;
                     throw new moodle_exception('errorcatcontextnotvalid', 'webservice', '', $exceptionparam);
                 }
+            }
+
+            // Return the category information
+            if (!isset($excludedcats[$category->id])) {
+
+                // Final check to see if the category is visible to the user
+                if ($category->visible
+                        or has_capability('moodle/category:viewhiddencategories', context_system::instance())
+                        or has_capability('moodle/category:manage', $context)) {
 
                     $categoryinfo = array();
                     $categoryinfo['id'] = $category->id;
                     $categoryinfo['name'] = $category->name;
-            $categoryinfo['description'] = $category->description;
+                    $categoryinfo['description'] = file_rewrite_pluginfile_urls($category->description,
-            $categoryinfo['descriptionformat'] = $category->descriptionformat;
+                            'webservice/pluginfile.php', $context->id, 'coursecat', 'description', null);
+                    $options = new stdClass;
+                    $options->noclean = true;
+                    $options->para = false;
+                    $categoryinfo['description'] = format_text($categoryinfo['description'],
+                            $category->descriptionformat, $options);
                     $categoryinfo['parent'] = $category->parent;
                     $categoryinfo['sortorder'] = $category->sortorder;
                     $categoryinfo['coursecount'] = $category->coursecount;
                     $categoryinfo['depth'] = $category->depth;
                     $categoryinfo['path'] = $category->path;
 
+                    //some fields only returned for admin
                     if (has_capability('moodle/category:manage', $context)) {
                         $categoryinfo['idnumber'] = $category->idnumber;
                         $categoryinfo['visible'] = $category->visible;
@@ -326,8 +373,10 @@ class core_course_external extends external_api {
                         $categoryinfo['theme'] = $category->theme;
                     }
 
-            if ($category->visible or has_capability('moodle/category:viewhiddencategories', context_system::instance())) {
                     $categoriesinfo[] = $categoryinfo;
+                } else {
+                    $excludedcats[$category->id] = 'visibility';
+                }
             }
         }
 
@@ -336,7 +385,9 @@ class core_course_external extends external_api {
 
     /**
      * Returns description of method result value
+     *
      * @return external_description
+     * @since Moodle 2.3
      */
     public static function get_categories_returns() {
         return new external_multiple_structure(
@@ -345,8 +396,7 @@ class core_course_external extends external_api {
                     'id' => new external_value(PARAM_INT, 'category id'),
                     'name' => new external_value(PARAM_TEXT, 'category name'),
                     'idnumber' => new external_value(PARAM_RAW, 'category id number', VALUE_OPTIONAL),
-                    'description' => new external_value(PARAM_TEXT, 'category description'),
+                    'description' => new external_value(PARAM_RAW, 'category description'),
-                    'descriptionformat' => new external_value(PARAM_INT, 'description format'),
                     'parent' => new external_value(PARAM_INT, 'parent category id'),
                     'sortorder' => new external_value(PARAM_INT, 'category sorting order'),
                     'coursecount' => new external_value(PARAM_INT, 'number of courses in this category'),
@@ -365,16 +415,15 @@ class core_course_external extends external_api {
      * Returns description of method parameters
      * @return external_function_parameters
      */
-    function get_categories_parameters() {
+    public static function get_courses_parameters() {
         return new external_function_parameters(
-            array(
+                array('options' => new external_single_structure(
-                options => new external_single_structure(
+                            array('ids' => new external_multiple_structure(
-                    array(
+                                        new external_value(PARAM_INT, 'Course id')
-                        'categoryid' => new external_value(PARAM_INT, 'category id to be returned', VALUE_OPTIONAL),
+                                        , 'List of course id. If empty return all courses
-                        'nosubcategories' => new external_value(PARAM_BOOL, 'return just the requested category
+                                            except front page course.',
-                                                        (true) or also its subcategories (false)', VALUE_DEFAULT, false)
+                                        VALUE_OPTIONAL)
-                    ), 'options', VALUE_DEFAULT, array()
+                            ), 'options - operator OR is used', VALUE_DEFAULT, array())
-                )
                 )
         );
     }

lib/db/services.php

@@ -381,9 +381,9 @@ $functions = array(
         'classname'   => 'core_course_external',
         'methodname'  => 'get_categories',
         'classpath'   => 'course/externallib.php',
-        'description' => 'Return category details',
+        'description' => 'Return categories details',
         'type'        => 'read',
-        'capabilities'=> 'moodle/category:viewhiddencategories',
+        'capabilities'=> '',
     ),
 
     'moodle_course_get_courses' => array(