MDL-71031 external: Minor tweaks towards coding style and external rules

- Some small namespace/use/MOODLE_INTERNAL/requires reorganization.
- Move file phpdocs to class phpdocs.
- Move external method names to be new "execute" default ones.
- Move unit tests to matching core_grades\external namespace.
- Add missing clean_returnvalue() calls.

grade/classes/external/create_gradecategories.php

@@ -14,6 +14,21 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+namespace core_grades\external;
+
+use external_api;
+use external_function_parameters;
+use external_value;
+use external_single_structure;
+use external_multiple_structure;
+use external_warnings;
+
+defined('MOODLE_INTERNAL') || die;
+
+require_once("$CFG->libdir/externallib.php");
+require_once("$CFG->libdir/gradelib.php");
+require_once("$CFG->dirroot/grade/edit/tree/lib.php");
+
 /**
  * Create gradecategories webservice.
  *
@@ -22,30 +37,14 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  * @since      Moodle 3.11
  */
-
-namespace core_grades\external;
-defined('MOODLE_INTERNAL') || die;
-use \external_function_parameters,
-    \external_value,
-    \external_single_structure,
-    \external_multiple_structure,
-    \external_warnings;
-
-require_once("$CFG->libdir/externallib.php");
-require_once("$CFG->libdir/gradelib.php");
-require_once("$CFG->dirroot/grade/edit/tree/lib.php");
-
-/**
- * Parameter, returns and webservice definitions for create_gradecategories.
- */
-class create_gradecategories extends \external_api {
+class create_gradecategories extends external_api {
     /**
      * Returns description of method parameters
      *
      * @return external_function_parameters
      * @since Moodle 3.11
      */
-    public static function create_gradecategories_parameters() {
+    public static function execute_parameters(): external_function_parameters {
         return new external_function_parameters(
             [
                 'courseid' => new external_value(PARAM_INT, 'id of course', VALUE_REQUIRED),
@@ -86,9 +85,10 @@ class create_gradecategories extends \external_api {
      * @param int $courseid the courseid to create the gradecategory in.
      * @param array $categories the categories to create.
      * @return array array of created categoryids and warnings.
+     * @since Moodle 3.11
      */
-    public static function create_gradecategories(int $courseid, array $categories) {
-        $params = self::validate_parameters(self::create_gradecategories_parameters(),
+    public static function execute(int $courseid, array $categories): array {
+        $params = self::validate_parameters(self::execute_parameters(),
             ['courseid' => $courseid, 'categories' => $categories]);
 
         // Now params are validated, update the references.
@@ -106,10 +106,10 @@ class create_gradecategories extends \external_api {
     /**
      * Returns description of method result value
      *
-     * @return external_description
+     * @return external_single_structure
      * @since Moodle 3.11
      */
-    public static function create_gradecategories_returns() {
+    public static function execute_returns(): external_single_structure {
         return new external_single_structure([
             'categoryids' => new external_multiple_structure(
                 new external_value(PARAM_INT, 'created cateogry ID')

grade/tests/external/create_gradecategories_test.php

@@ -14,6 +14,17 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+namespace core_grades\external;
+
+use core_grades\external\create_gradecategories;
+use external_api;
+
+defined('MOODLE_INTERNAL') || die;
+
+global $CFG;
+
+require_once($CFG->dirroot . '/webservice/tests/helpers.php');
+
 /**
  * Unit tests for the core_grades\external\create_gradecategories webservice.
  *
@@ -23,17 +34,7 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  * @since      Moodle 3.11
  */
-
-defined('MOODLE_INTERNAL') || die();
-global $CFG;
-require_once($CFG->dirroot . '/webservice/tests/helpers.php');
-
-use \core_grades\external\create_gradecategories;
-
-/**
- * create_gradecategories unit tests.
- */
-class create_gradecategories_testcase extends externallib_advanced_testcase {
+class create_gradecategories_testcase extends \externallib_advanced_testcase {
 
     /**
      * Test create_gradecategories.
@@ -47,10 +48,11 @@ class create_gradecategories_testcase extends externallib_advanced_testcase {
         $this->setAdminUser();
 
         // Test the most basic gradecategory creation.
-        $status1 = create_gradecategories::create_gradecategories($course->id,
+        $status1 = create_gradecategories::execute($course->id,
             [['fullname' => 'Test Category 1', 'options' => []]]);
+        $status1 = external_api::clean_returnvalue(create_gradecategories::execute_returns(), $status1);
 
-        $courseparentcat = grade_category::fetch_course_category($course->id);
+        $courseparentcat = \grade_category::fetch_course_category($course->id);
         $record1 = $DB->get_record('grade_categories', ['id' => $status1['categoryids'][0]]);
         $this->assertEquals('Test Category 1', $record1->fullname);
         // Confirm that the parent category for this category is the top level category for the course.
@@ -58,8 +60,9 @@ class create_gradecategories_testcase extends externallib_advanced_testcase {
         $this->assertEquals(2, $record1->depth);
 
         // Now create a category as a child of the newly created category.
-        $status2 = create_gradecategories::create_gradecategories($course->id,
+        $status2 = create_gradecategories::execute($course->id,
             [['fullname' => 'Test Category 2', 'options' => ['parentcategoryid' => $record1->id]]]);
+        $status2 = external_api::clean_returnvalue(create_gradecategories::execute_returns(), $status2);
         $record2 = $DB->get_record('grade_categories', ['id' => $status2['categoryids'][0]]);
         $this->assertEquals($record1->id, $record2->parent);
         $this->assertEquals(3, $record2->depth);
@@ -89,9 +92,10 @@ class create_gradecategories_testcase extends externallib_advanced_testcase {
             'parentcategoryid' => $record2->id
         ];
 
-        $status3 = create_gradecategories::create_gradecategories($course->id,
+        $status3 = create_gradecategories::execute($course->id,
             [['fullname' => 'Test Category 3', 'options' => $customopts]]);
-        $cat3 = new grade_category(['courseid' => $course->id, 'id' => $status3['categoryids'][0]], true);
+        $status3 = external_api::clean_returnvalue(create_gradecategories::execute_returns(), $status3);
+        $cat3 = new \grade_category(['courseid' => $course->id, 'id' => $status3['categoryids'][0]], true);
         $cat3->load_grade_item();
 
         // Lets check all of the data is in the right shape.
@@ -116,7 +120,7 @@ class create_gradecategories_testcase extends externallib_advanced_testcase {
         $this->assertEquals($record2->id, $cat3->parent);
 
         // Now test creating 2 in parallel, and nesting them.
-        $status4 = create_gradecategories::create_gradecategories($course->id, [
+        $status4 = create_gradecategories::execute($course->id, [
             [
                 'fullname' => 'Test Category 4',
                 'options' => [
@@ -131,6 +135,7 @@ class create_gradecategories_testcase extends externallib_advanced_testcase {
                 ],
             ],
         ]);
+        $status4 = external_api::clean_returnvalue(create_gradecategories::execute_returns(), $status4);
 
         $secondlevel = $DB->get_record('grade_categories', ['id' => $status4['categoryids'][0]]);
         $thirdlevel = $DB->get_record('grade_categories', ['id' => $status4['categoryids'][1]]);

lib/db/services.php

@@ -942,7 +942,6 @@ $functions = array(
     ),
     'core_grades_create_gradecategories' => array (
         'classname' => 'core_grades\external\create_gradecategories',
-        'methodname' => 'create_gradecategories',
         'description' => 'Create grade categories inside a course gradebook.',
         'type' => 'write',
         'capabilities' => 'moodle/grade:manage',