lib/classes/external/moodlenet_get_shared_course_info.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 namespace core\external;
  18
  19 use context_course;
  20 use core\moodlenet\utilities;
  21 use core\oauth2\api;
  22 use core_external\external_api;
  23 use core_external\external_function_parameters;
  24 use core_external\external_single_structure;
  25 use core_external\external_value;
  26 use core_external\external_warnings;
  27
  28 /**
  29  * The external API to get MoodleNet information about the course to be shared.
  30  *
  31  * @package    core
  32  * @copyright  2023 Safat Shahin <safat.shahin@gmail.com>
  33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34  * @since      Moodle 4.3
  35  */
  36 class moodlenet_get_shared_course_info extends external_api {
  37
  38     /**
  39      * Returns description of parameters.
  40      *
  41      * @return external_function_parameters
  42      */
  43     public static function execute_parameters(): external_function_parameters {
  44         return new external_function_parameters([
  45             'courseid' => new external_value(PARAM_INT, 'The course id', VALUE_REQUIRED),
  46         ]);
  47     }
  48
  49     /**
  50      * External function to get the course information.
  51      *
  52      * @param int $courseid The course id
  53      * @return array
  54      */
  55     public static function execute(int $courseid): array {
  56         global $USER;
  57
  58         [
  59             'courseid' => $courseid
  60         ] = self::validate_parameters(self::execute_parameters(), [
  61             'courseid' => $courseid
  62         ]);
  63
  64         // Get course.
  65         $course = get_course($courseid);
  66
  67         // Check capability.
  68         $coursecontext = context_course::instance($course->id);
  69         if (!utilities::can_user_share($coursecontext, $USER->id, 'course')) {
  70             return self::return_errors($courseid, 'errorpermission',
  71                 get_string('nopermissions', 'error', get_string('moodlenet:sharetomoodlenet', 'moodle')));
  72         }
  73
  74         $warnings = [];
  75         $supporturl = utilities::get_support_url();
  76         $issuerid = get_config('moodlenet', 'oauthservice');
  77
  78         if (empty($issuerid)) {
  79             return self::return_errors(0, 'errorissuernotset', get_string('moodlenet:issuerisnotset', 'moodle'));
  80         }
  81
  82         // Get the issuer.
  83         $issuer = api::get_issuer($issuerid);
  84         // Validate the issuer and check if it is enabled or not.
  85         if (!utilities::is_valid_instance($issuer)) {
  86             return self::return_errors($issuerid, 'errorissuernotenabled', get_string('moodlenet:issuerisnotenabled', 'moodle'));
  87         }
  88
  89         return [
  90             'status' => true,
  91             'name' => $course->fullname,
  92             'type' => get_string('course'),
  93             'server' => $issuer->get_display_name(),
  94             'supportpageurl' => $supporturl,
  95             'issuerid' => $issuerid,
  96             'warnings' => $warnings
  97         ];
  98     }
  99
 100     /**
 101      * Describes the data returned from the external function.
 102      *
 103      * @return external_single_structure
 104      */
 105     public static function execute_returns(): external_single_structure {
 106         return new external_single_structure([
 107             'name' => new external_value(PARAM_TEXT, 'Course short name'),
 108             'type' => new external_value(PARAM_TEXT, 'Course type'),
 109             'server' => new external_value(PARAM_TEXT, 'MoodleNet server'),
 110             'supportpageurl' => new external_value(PARAM_URL, 'Support page URL'),
 111             'issuerid' => new external_value(PARAM_INT, 'MoodleNet issuer id'),
 112             'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 113             'warnings' => new external_warnings()
 114         ]);
 115     }
 116
 117     /**
 118      * Handle return error.
 119      *
 120      * @param int $itemid Item id.
 121      * @param string $warningcode Warning code.
 122      * @param string $message Message.
 123      * @param int $issuerid Issuer id.
 124      * @return array
 125      */
 126     protected static function return_errors(int $itemid, string $warningcode, string $message, int $issuerid = 0): array {
 127         $warnings[] = [
 128             'item' => $itemid,
 129             'warningcode' => $warningcode,
 130             'message' => $message
 131         ];
 132
 133         return [
 134             'status' => false,
 135             'name' => '',
 136             'type' => '',
 137             'server' => '',
 138             'supportpageurl' => '',
 139             'issuerid' => $issuerid,
 140             'warnings' => $warnings
 141         ];
 142     }
 143 }