MDL-66061 comments: Support pagination and sorting in get_comments WS

comment/classes/external.php

@@ -49,12 +49,13 @@ class core_comment_external extends external_api {
 
         return new external_function_parameters(
             array(
-                'contextlevel' => new external_value(PARAM_ALPHA, 'contextlevel system, course, user...'),
-                'instanceid'   => new external_value(PARAM_INT, 'the Instance id of item associated with the context level'),
-                'component'    => new external_value(PARAM_COMPONENT, 'component'),
-                'itemid'       => new external_value(PARAM_INT, 'associated id'),
-                'area'         => new external_value(PARAM_AREA, 'string comment area', VALUE_DEFAULT, ''),
-                'page'         => new external_value(PARAM_INT, 'page number (0 based)', VALUE_DEFAULT, 0),
+                'contextlevel'  => new external_value(PARAM_ALPHA, 'contextlevel system, course, user...'),
+                'instanceid'    => new external_value(PARAM_INT, 'the Instance id of item associated with the context level'),
+                'component'     => new external_value(PARAM_COMPONENT, 'component'),
+                'itemid'        => new external_value(PARAM_INT, 'associated id'),
+                'area'          => new external_value(PARAM_AREA, 'string comment area', VALUE_DEFAULT, ''),
+                'page'          => new external_value(PARAM_INT, 'page number (0 based)', VALUE_DEFAULT, 0),
+                'sortdirection' => new external_value(PARAM_ALPHA, 'Sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC'),
             )
         );
     }
@@ -68,22 +69,33 @@ class core_comment_external extends external_api {
      * @param int $itemid the item id
      * @param string $area comment area
      * @param int $page page number
+     * @param string $sortdirection sort direction
      * @return array of comments and warnings
      * @since Moodle 2.9
      */
-    public static function get_comments($contextlevel, $instanceid, $component, $itemid, $area = '', $page = 0) {
+    public static function get_comments($contextlevel, $instanceid, $component, $itemid, $area = '', $page = 0,
+            $sortdirection = 'DESC') {
+        global $CFG;
 
         $warnings = array();
         $arrayparams = array(
-            'contextlevel' => $contextlevel,
-            'instanceid'   => $instanceid,
-            'component'    => $component,
-            'itemid'       => $itemid,
-            'area'         => $area,
-            'page'         => $page
+            'contextlevel'  => $contextlevel,
+            'instanceid'    => $instanceid,
+            'component'     => $component,
+            'itemid'        => $itemid,
+            'area'          => $area,
+            'page'          => $page,
+            'sortdirection' => $sortdirection,
         );
         $params = self::validate_parameters(self::get_comments_parameters(), $arrayparams);
 
+        $sortdirection = strtoupper($params['sortdirection']);
+        $directionallowedvalues = array('ASC', 'DESC');
+        if (!in_array($sortdirection, $directionallowedvalues)) {
+            throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
+                'allowed values are: ' . implode(',', $directionallowedvalues));
+        }
+
         $context = self::get_context_from_params($params);
         self::validate_context($context);
 
@@ -96,7 +108,7 @@ class core_comment_external extends external_api {
         $args->component = $params['component'];
 
         $commentobject = new comment($args);
-        $comments = $commentobject->get_comments($params['page']);
+        $comments = $commentobject->get_comments($params['page'], $sortdirection);
 
         // False means no permissions to see comments.
         if ($comments === false) {
@@ -117,6 +129,8 @@ class core_comment_external extends external_api {
 
         $results = array(
             'comments' => $comments,
+            'count' => $commentobject->count(),
+            'perpage' => (!empty($CFG->commentsperpage)) ? $CFG->commentsperpage : 15,
             'warnings' => $warnings
         );
         return $results;
@@ -148,6 +162,8 @@ class core_comment_external extends external_api {
                         ), 'comment'
                     ), 'List of comments'
                 ),
+                'count' => new external_value(PARAM_INT,  'Total number of comments.', VALUE_OPTIONAL),
+                'perpage' => new external_value(PARAM_INT,  'Number of comments per page.', VALUE_OPTIONAL),
                 'warnings' => new external_warnings()
             )
         );

comment/lib.php

@@ -537,9 +537,10 @@ class comment {
      * Return matched comments
      *
      * @param  int $page
+     * @param  str $sortdirection sort direction, ASC or DESC
      * @return array
      */
-    public function get_comments($page = '') {
+    public function get_comments($page = '', $sortdirection = 'DESC') {
         global $DB, $CFG, $USER, $OUTPUT;
         if (!$this->can_view()) {
             return false;
@@ -557,6 +558,7 @@ class comment {
             $params['component'] = $component;
         }
 
+        $sortdirection = ($sortdirection === 'ASC') ? 'ASC' : 'DESC';
         $sql = "SELECT $ufields, c.id AS cid, c.content AS ccontent, c.format AS cformat, c.timecreated AS ctimecreated
                   FROM {comments} c
                   JOIN {user} u ON u.id = c.userid
@@ -564,7 +566,7 @@ class comment {
                        c.commentarea = :commentarea AND
                        c.itemid = :itemid AND
                        $componentwhere
-              ORDER BY c.timecreated DESC";
+              ORDER BY c.timecreated $sortdirection";
         $params['contextid'] = $this->contextid;
         $params['commentarea'] = $this->commentarea;
         $params['itemid'] = $this->itemid;

comment/tests/externallib_test.php

@@ -123,11 +123,34 @@ class core_comment_externallib_testcase extends externallib_advanced_testcase {
 
         $this->assertCount(0, $result['warnings']);
         $this->assertCount(2, $result['comments']);
+        $this->assertEquals(2, $result['count']);
+        $this->assertEquals(15, $result['perpage']);
 
         $this->assertEquals($user->id, $result['comments'][0]['userid']);
         $this->assertEquals($user->id, $result['comments'][1]['userid']);
 
-        $this->assertEquals($cmtid2, $result['comments'][0]['id']);
+        $this->assertEquals($cmtid2, $result['comments'][0]['id']); // Default ordering newer first.
         $this->assertEquals($cmtid1, $result['comments'][1]['id']);
+
+        // Test sort direction and pagination.
+        $CFG->commentsperpage = 1;
+        $result = core_comment_external::get_comments($contextlevel, $instanceid, $component, $itemid, $area, $page, 'ASC');
+        $result = external_api::clean_returnvalue(core_comment_external::get_comments_returns(), $result);
+
+        $this->assertCount(0, $result['warnings']);
+        $this->assertCount(1, $result['comments']); // Only one per page.
+        $this->assertEquals(2, $result['count']);
+        $this->assertEquals($CFG->commentsperpage, $result['perpage']);
+        $this->assertEquals($cmtid1, $result['comments'][0]['id']); // Comments order older first.
+
+        // Next page.
+        $result = core_comment_external::get_comments($contextlevel, $instanceid, $component, $itemid, $area, $page + 1, 'ASC');
+        $result = external_api::clean_returnvalue(core_comment_external::get_comments_returns(), $result);
+
+        $this->assertCount(0, $result['warnings']);
+        $this->assertCount(1, $result['comments']);
+        $this->assertEquals(2, $result['count']);
+        $this->assertEquals($CFG->commentsperpage, $result['perpage']);
+        $this->assertEquals($cmtid2, $result['comments'][0]['id']);
     }
 }

comment/upgrade.txt

+This files describes API changes in /comment/* ,
+information provided here is intended especially for developers.
+
+=== 3.8 ===
+  * External function get_comments now returns the total count of comments and the number of comments per page.
+    It also has a new parameter to indicate the sorting direction (defaulted to DESC).
+