5fbfd2052d816c905ae4f916ade9342799a78172
[moodle.git] / admin / tool / moodlenet / classes / external.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/>.
17 /**
18  * This is the external API for this component.
19  *
20  * @package    tool_moodlenet
21  * @copyright  2020 Mathew May {@link https://mathew.solutions}
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace tool_moodlenet;
27 defined('MOODLE_INTERNAL') || die();
29 require_once($CFG->libdir .'/externallib.php');
30 require_once($CFG->libdir . '/filelib.php');
31 require_once(__DIR__ . '/../lib.php');
33 use core_course\external\course_summary_exporter;
34 use external_api;
35 use external_function_parameters;
36 use external_value;
37 use external_single_structure;
39 /**
40  * This is the external API for this component.
41  *
42  * @copyright  2020 Mathew May {@link https://mathew.solutions}
43  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
44  */
45 class external extends external_api {
47     /**
48      * verify_webfinger parameters
49      *
50      * @return external_function_parameters
51      */
52     public static function verify_webfinger_parameters() {
53         return new external_function_parameters(
54             array(
55                 'profileurl' => new external_value(PARAM_RAW, 'The profile url that the user has given us', VALUE_REQUIRED),
56                 'course' => new external_value(PARAM_INT, 'The course we are adding to', VALUE_REQUIRED),
57                 'section' => new external_value(PARAM_INT, 'The section within the course we are adding to', VALUE_REQUIRED),
58             )
59         );
60     }
62     /**
63      * Figure out if the passed content resolves with a WebFinger account.
64      *
65      * @param string $profileurl The profile url that the user states exists
66      * @param int $course The course we are adding to
67      * @param int $section The section within the course we are adding to
68      * @return array Contains the result and domain if any
69      * @throws \invalid_parameter_exception
70      */
71     public static function verify_webfinger(string $profileurl, int $course, int $section) {
72         global $USER;
74         $params = self::validate_parameters(self::verify_webfinger_parameters(), [
75                 'profileurl' => $profileurl,
76                 'section' => $section,
77                 'course' => $course
78             ]
79         );
80         try {
81             $mnetprofile = new moodlenet_user_profile($params['profileurl'], $USER->id);
82         } catch (\Exception $e) {
83             return [
84                 'result' => false,
85                 'message' => get_string('profilevalidationfail', 'tool_moodlenet'),
86             ];
87         }
89         $userlink = profile_manager::get_moodlenet_profile_link($mnetprofile);
91         // There were no problems verifying the account so lets store it.
92         if ($userlink['result'] === true) {
93             profile_manager::save_moodlenet_user_profile($mnetprofile);
94             $userlink['domain'] = generate_mnet_endpoint($mnetprofile->get_profile_name(), $course, $section);
95         }
97         return $userlink;
98     }
100     /**
101      * verify_webfinger return.
102      *
103      * @return \external_description
104      */
105     public static function verify_webfinger_returns() {
106         return new external_single_structure([
107             'result' => new external_value(PARAM_BOOL, 'Was the passed content a valid WebFinger?'),
108             'message' => new external_value(PARAM_TEXT, 'Our message for the user'),
109             'domain' => new external_value(PARAM_RAW, 'Domain to redirect the user to', VALUE_OPTIONAL),
110         ]);
111     }
113     /**
114      * search_courses_parameters
115      *
116      * @return external_function_parameters
117      */
118     public static function search_courses_parameters() {
119         return new external_function_parameters(
120             array(
121                 'searchvalue' => new external_value(PARAM_RAW, 'search value'),
122             )
123         );
124     }
126     /**
127      * For some given input find and return any course that matches it.
128      *
129      * @param string $searchvalue The profile url that the user states exists
130      * @return array Contains the result set of courses for the value
131      */
132     public static function search_courses(string $searchvalue) {
133         global $OUTPUT;
135         $params = self::validate_parameters(
136             self::search_courses_parameters(),
137             ['searchvalue' => $searchvalue]
138         );
139         self::validate_context(\context_system::instance());
141         $courses = array();
143         if ($arrcourses = \core_course_category::search_courses(array('search' => $params['searchvalue']))) {
144             foreach ($arrcourses as $course) {
145                 if (has_capability('moodle/course:manageactivities', \context_course::instance($course->id))) {
146                     $data = new \stdClass();
147                     $data->id = $course->id;
148                     $data->fullname = $course->fullname;
149                     $data->hidden = $course->visible;
150                     $options = [
151                         'course' => $course->id,
152                     ];
153                     $viewurl = new \moodle_url('/admin/tool/moodlenet/options.php', $options);
154                     $data->viewurl = $viewurl->out(false);
155                     $category = \core_course_category::get($course->category);
156                     $data->coursecategory = $category->name;
157                     $courseimage = course_summary_exporter::get_course_image($data);
158                     if (!$courseimage) {
159                         $courseimage = $OUTPUT->get_generated_image_for_id($data->id);
160                     }
161                     $data->courseimage = $courseimage;
162                     $courses[] = $data;
163                 }
164             }
165         }
166         return array(
167             'courses' => $courses
168         );
169     }
171     /**
172      * search_courses_returns.
173      *
174      * @return \external_description
175      */
176     public static function search_courses_returns() {
177         return new external_single_structure([
178             'courses' => new \external_multiple_structure(
179                 new external_single_structure([
180                     'id' => new external_value(PARAM_INT, 'course id'),
181                     'fullname' => new external_value(PARAM_TEXT, 'course full name'),
182                     'hidden' => new external_value(PARAM_INT, 'is the course visible'),
183                     'viewurl' => new external_value(PARAM_URL, 'Next step of import'),
184                     'coursecategory' => new external_value(PARAM_TEXT, 'Category name'),
185                     'courseimage' => new external_value(PARAM_RAW, 'course image'),
186                 ]))
187         ]);
188     }