Automatically generated installer lang files
[moodle.git] / notes / externallib.php
blobc393fd81b30a5f1cbac35c9b69d81ea03e9caf98
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.
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/>.
18 /**
19 * External notes API
21 * @package core_notes
22 * @category external
23 * @copyright 2011 Jerome Mouneyrac
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 defined('MOODLE_INTERNAL') || die();
29 require_once("$CFG->libdir/externallib.php");
30 require_once($CFG->dirroot . "/notes/lib.php");
32 /**
33 * Notes external functions
35 * @package core_notes
36 * @category external
37 * @copyright 2011 Jerome Mouneyrac
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39 * @since Moodle 2.2
41 class core_notes_external extends external_api {
43 /**
44 * Returns description of method parameters
46 * @return external_function_parameters
47 * @since Moodle 2.2
49 public static function create_notes_parameters() {
50 return new external_function_parameters(
51 array(
52 'notes' => new external_multiple_structure(
53 new external_single_structure(
54 array(
55 'userid' => new external_value(PARAM_INT, 'id of the user the note is about'),
56 'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\''),
57 'courseid' => new external_value(PARAM_INT, 'course id of the note (in Moodle a note can only be created into a course, even for site and personal notes)'),
58 'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML'),
59 'format' => new external_format_value('text', VALUE_DEFAULT),
60 'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own client id for the note. If this id is provided, the fail message id will be returned to you', VALUE_OPTIONAL),
68 /**
69 * Create notes about some users
70 * Note: code should be matching the /notes/edit.php checks
71 * and the /user/addnote.php checks. (they are similar cheks)
73 * @param array $notes An array of notes to create.
74 * @return array (success infos and fail infos)
75 * @since Moodle 2.2
77 public static function create_notes($notes = array()) {
78 global $CFG, $DB;
80 $params = self::validate_parameters(self::create_notes_parameters(), array('notes' => $notes));
82 // Check if note system is enabled.
83 if (!$CFG->enablenotes) {
84 throw new moodle_exception('notesdisabled', 'notes');
87 // Retrieve all courses.
88 $courseids = array();
89 foreach ($params['notes'] as $note) {
90 $courseids[] = $note['courseid'];
92 $courses = $DB->get_records_list("course", "id", $courseids);
94 // Retrieve all users of the notes.
95 $userids = array();
96 foreach ($params['notes'] as $note) {
97 $userids[] = $note['userid'];
99 list($sqluserids, $sqlparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'userid_');
100 $users = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
102 $resultnotes = array();
103 foreach ($params['notes'] as $note) {
105 $success = true;
106 $resultnote = array(); // The infos about the success of the operation.
108 // Check the course exists.
109 if (empty($courses[$note['courseid']])) {
110 $success = false;
111 $errormessage = get_string('invalidcourseid', 'error');
112 } else {
113 // Ensure the current user is allowed to run this function.
114 $context = context_course::instance($note['courseid']);
115 self::validate_context($context);
116 require_capability('moodle/notes:manage', $context);
119 // Check the user exists.
120 if (empty($users[$note['userid']])) {
121 $success = false;
122 $errormessage = get_string('invaliduserid', 'notes', $note['userid']);
125 // Build the resultnote.
126 if (isset($note['clientnoteid'])) {
127 $resultnote['clientnoteid'] = $note['clientnoteid'];
130 if ($success) {
131 // Now we can create the note.
132 $dbnote = new stdClass;
133 $dbnote->courseid = $note['courseid'];
134 $dbnote->userid = $note['userid'];
135 // Need to support 'html' and 'text' format values for backward compatibility.
136 switch (strtolower($note['format'])) {
137 case 'html':
138 $textformat = FORMAT_HTML;
139 break;
140 case 'text':
141 $textformat = FORMAT_PLAIN;
142 default:
143 $textformat = external_validate_format($note['format']);
144 break;
146 $dbnote->content = $note['text'];
147 $dbnote->format = $textformat;
149 // Get the state ('personal', 'course', 'site').
150 switch ($note['publishstate']) {
151 case 'personal':
152 $dbnote->publishstate = NOTES_STATE_DRAFT;
153 break;
154 case 'course':
155 $dbnote->publishstate = NOTES_STATE_PUBLIC;
156 break;
157 case 'site':
158 $dbnote->publishstate = NOTES_STATE_SITE;
159 $dbnote->courseid = SITEID;
160 break;
161 default:
162 break;
165 // TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once
166 if (note_save($dbnote)) { // Note_save attribut an id in case of success.
167 $success = $dbnote->id;
170 $resultnote['noteid'] = $success;
171 } else {
172 // WARNINGS: for backward compatibility we return this errormessage.
173 // We should have thrown exceptions as these errors prevent results to be returned.
174 // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side .
175 $resultnote['noteid'] = -1;
176 $resultnote['errormessage'] = $errormessage;
179 $resultnotes[] = $resultnote;
182 return $resultnotes;
186 * Returns description of method result value
188 * @return external_description
189 * @since Moodle 2.2
191 public static function create_notes_returns() {
192 return new external_multiple_structure(
193 new external_single_structure(
194 array(
195 'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the note', VALUE_OPTIONAL),
196 'noteid' => new external_value(PARAM_INT, 'ID of the created note when successful, -1 when failed'),
197 'errormessage' => new external_value(PARAM_TEXT, 'error message - if failed', VALUE_OPTIONAL)
204 * Returns description of delete_notes parameters
206 * @return external_function_parameters
207 * @since Moodle 2.5
209 public static function delete_notes_parameters() {
210 return new external_function_parameters(
211 array(
212 "notes"=> new external_multiple_structure(
213 new external_value(PARAM_INT, 'ID of the note to be deleted'), 'Array of Note Ids to be deleted.'
220 * Delete notes about users.
221 * Note: code should be matching the /notes/delete.php checks.
223 * @param array $notes An array of ids for the notes to delete.
224 * @return null
225 * @since Moodle 2.5
227 public static function delete_notes($notes = array()) {
228 global $CFG;
230 $params = self::validate_parameters(self::delete_notes_parameters(), array('notes' => $notes));
232 // Check if note system is enabled.
233 if (!$CFG->enablenotes) {
234 throw new moodle_exception('notesdisabled', 'notes');
236 $warnings = array();
237 foreach ($params['notes'] as $noteid) {
238 $note = note_load($noteid);
239 if (isset($note->id)) {
240 // Ensure the current user is allowed to run this function.
241 $context = context_course::instance($note->courseid);
242 self::validate_context($context);
243 require_capability('moodle/notes:manage', $context);
244 note_delete($note);
245 } else {
246 $warnings[] = array('item'=>'note', 'itemid'=>$noteid, 'warningcode'=>'badid', 'message'=>'Note does not exist');
249 return $warnings;
253 * Returns description of delete_notes result value.
255 * @return external_description
256 * @since Moodle 2.5
258 public static function delete_notes_returns() {
259 return new external_warnings('item is always \'note\'',
260 'When errorcode is savedfailed the note could not be modified.' .
261 'When errorcode is badparam, an incorrect parameter was provided.' .
262 'When errorcode is badid, the note does not exist',
263 'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
268 * Returns description of get_notes parameters.
270 * @return external_function_parameters
271 * @since Moodle 2.5
273 public static function get_notes_parameters() {
274 return new external_function_parameters(
275 array(
276 "notes"=> new external_multiple_structure(
277 new external_value(PARAM_INT, 'ID of the note to be retrieved'), 'Array of Note Ids to be retrieved.'
284 * Get notes about users.
286 * @param array $notes An array of ids for the notes to retrieve.
287 * @return null
288 * @since Moodle 2.5
290 public static function get_notes($notes) {
291 global $CFG;
293 $params = self::validate_parameters(self::get_notes_parameters(), array('notes' => $notes));
294 // Check if note system is enabled.
295 if (!$CFG->enablenotes) {
296 throw new moodle_exception('notesdisabled', 'notes');
298 $resultnotes = array();
299 foreach ($params['notes'] as $noteid) {
300 $resultnote = array();
302 $note = note_load($noteid);
303 if (isset($note->id)) {
304 // Ensure the current user is allowed to run this function.
305 $context = context_course::instance($note->courseid);
306 self::validate_context($context);
307 require_capability('moodle/notes:view', $context);
308 list($gotnote['text'], $gotnote['format']) = external_format_text($note->content,
309 $note->format,
310 $context->id,
311 'notes',
313 '');
314 $gotnote['noteid'] = $note->id;
315 $gotnote['userid'] = $note->userid;
316 $gotnote['publishstate'] = $note->publishstate;
317 $gotnote['courseid'] = $note->courseid;
318 $resultnotes["notes"][] = $gotnote;
319 } else {
320 $resultnotes["warnings"][] = array('item' => 'note',
321 'itemid' => $noteid,
322 'warningcode' => 'badid',
323 'message' => 'Note does not exist');
326 return $resultnotes;
330 * Returns description of get_notes result value.
332 * @return external_description
333 * @since Moodle 2.5
335 public static function get_notes_returns() {
336 return new external_single_structure(
337 array(
338 'notes' => new external_multiple_structure(
339 new external_single_structure(
340 array(
341 'noteid' => new external_value(PARAM_INT, 'id of the note', VALUE_OPTIONAL),
342 'userid' => new external_value(PARAM_INT, 'id of the user the note is about', VALUE_OPTIONAL),
343 'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\'', VALUE_OPTIONAL),
344 'courseid' => new external_value(PARAM_INT, 'course id of the note', VALUE_OPTIONAL),
345 'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML', VALUE_OPTIONAL),
346 'format' => new external_format_value('text', VALUE_OPTIONAL),
347 ), 'note'
350 'warnings' => new external_warnings('item is always \'note\'',
351 'When errorcode is savedfailed the note could not be modified.' .
352 'When errorcode is badparam, an incorrect parameter was provided.' .
353 'When errorcode is badid, the note does not exist',
354 'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)')
360 * Returns description of update_notes parameters.
362 * @return external_function_parameters
363 * @since Moodle 2.5
365 public static function update_notes_parameters() {
366 return new external_function_parameters(
367 array(
368 'notes' => new external_multiple_structure(
369 new external_single_structure(
370 array(
371 'id' => new external_value(PARAM_INT, 'id of the note'),
372 'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\''),
373 'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML'),
374 'format' => new external_format_value('text', VALUE_DEFAULT),
376 ), "Array of Notes", VALUE_DEFAULT, array()
383 * Update notes about users.
385 * @param array $notes An array of ids for the notes to update.
386 * @return array fail infos.
387 * @since Moodle 2.2
389 public static function update_notes($notes = array()) {
390 global $CFG, $DB;
392 $params = self::validate_parameters(self::update_notes_parameters(), array('notes' => $notes));
394 // Check if note system is enabled.
395 if (!$CFG->enablenotes) {
396 throw new moodle_exception('notesdisabled', 'notes');
399 $warnings = array();
400 foreach ($params['notes'] as $note) {
401 $notedetails = note_load($note['id']);
402 if (isset($notedetails->id)) {
403 // Ensure the current user is allowed to run this function.
404 $context = context_course::instance($notedetails->courseid);
405 self::validate_context($context);
406 require_capability('moodle/notes:manage', $context);
408 $dbnote = new stdClass;
409 $dbnote->id = $note['id'];
410 $dbnote->content = $note['text'];
411 $dbnote->format = external_validate_format($note['format']);
412 // Get the state ('personal', 'course', 'site').
413 switch ($note['publishstate']) {
414 case 'personal':
415 $dbnote->publishstate = NOTES_STATE_DRAFT;
416 break;
417 case 'course':
418 $dbnote->publishstate = NOTES_STATE_PUBLIC;
419 break;
420 case 'site':
421 $dbnote->publishstate = NOTES_STATE_SITE;
422 $dbnote->courseid = SITEID;
423 break;
424 default:
425 $warnings[] = array('item' => 'note',
426 'itemid' => $note["id"],
427 'warningcode' => 'badparam',
428 'message' => 'Provided publishstate incorrect');
429 break;
431 if (!note_save($dbnote)) {
432 $warnings[] = array('item' => 'note',
433 'itemid' => $note["id"],
434 'warningcode' => 'savedfailed',
435 'message' => 'Note could not be modified');
437 } else {
438 $warnings[] = array('item' => 'note',
439 'itemid' => $note["id"],
440 'warningcode' => 'badid',
441 'message' => 'Note does not exist');
444 return $warnings;
448 * Returns description of update_notes result value.
450 * @return external_description
451 * @since Moodle 2.5
453 public static function update_notes_returns() {
454 return new external_warnings('item is always \'note\'',
455 'When errorcode is savedfailed the note could not be modified.' .
456 'When errorcode is badparam, an incorrect parameter was provided.' .
457 'When errorcode is badid, the note does not exist',
458 'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
462 * Returns description of method parameters
464 * @return external_function_parameters
465 * @since Moodle 2.9
467 public static function get_course_notes_parameters() {
468 return new external_function_parameters(
469 array(
470 'courseid' => new external_value(PARAM_INT, 'course id, 0 for SITE'),
471 'userid' => new external_value(PARAM_INT, 'user id', VALUE_DEFAULT, 0),
477 * Create a notes list
479 * @param int $courseid ID of the Course
480 * @param stdClass $context context object
481 * @param int $userid ID of the User
482 * @param int $state
483 * @param int $author
484 * @return array of notes
485 * @since Moodle 2.9
487 protected static function create_note_list($courseid, $context, $userid, $state, $author = 0) {
488 $results = array();
489 $notes = note_list($courseid, $userid, $state, $author);
490 foreach ($notes as $key => $note) {
491 $note = (array)$note;
492 list($note['content'], $note['format']) = external_format_text($note['content'],
493 $note['format'],
494 $context->id,
498 $results[$key] = $note;
500 return $results;
504 * Get a list of course notes
506 * @param int $courseid ID of the Course
507 * @param int $userid ID of the User
508 * @return array of site, course and personal notes and warnings
509 * @since Moodle 2.9
510 * @throws moodle_exception
512 public static function get_course_notes($courseid, $userid = 0) {
513 global $CFG, $USER;
515 if (empty($CFG->enablenotes)) {
516 throw new moodle_exception('notesdisabled', 'notes');
519 $warnings = array();
520 $arrayparams = array(
521 'courseid' => $courseid,
522 'userid' => $userid,
524 $params = self::validate_parameters(self::get_course_notes_parameters(), $arrayparams);
526 if (empty($params['courseid'])) {
527 $params['courseid'] = SITEID;
529 $user = null;
530 if (!empty($params['userid'])) {
531 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
532 core_user::require_active_user($user);
535 $course = get_course($params['courseid']);
537 if ($course->id == SITEID) {
538 $context = context_system::instance();
539 } else {
540 $context = context_course::instance($course->id);
542 self::validate_context($context);
544 $sitenotes = array();
545 $coursenotes = array();
546 $personalnotes = array();
548 if ($course->id != SITEID) {
550 require_capability('moodle/notes:view', $context);
551 $sitenotes = self::create_note_list(0, context_system::instance(), $params['userid'], NOTES_STATE_SITE);
552 $coursenotes = self::create_note_list($course->id, $context, $params['userid'], NOTES_STATE_PUBLIC);
553 $personalnotes = self::create_note_list($course->id, $context, $params['userid'], NOTES_STATE_DRAFT,
554 $USER->id);
555 } else {
556 if (has_capability('moodle/notes:view', $context)) {
557 $sitenotes = self::create_note_list(0, $context, $params['userid'], NOTES_STATE_SITE);
559 // It returns notes only for a specific user!
560 if (!empty($user)) {
561 $usercourses = enrol_get_users_courses($user->id, true);
562 foreach ($usercourses as $c) {
563 // All notes at course level, only if we have capability on every course.
564 if (has_capability('moodle/notes:view', context_course::instance($c->id))) {
565 $coursenotes += self::create_note_list($c->id, $context, $params['userid'], NOTES_STATE_PUBLIC);
571 $results = array(
572 'sitenotes' => $sitenotes,
573 'coursenotes' => $coursenotes,
574 'personalnotes' => $personalnotes,
575 'warnings' => $warnings
577 return $results;
582 * Returns array of note structure
584 * @return external_description
585 * @since Moodle 2.9
587 protected static function get_note_structure() {
588 return array(
589 'id' => new external_value(PARAM_INT, 'id of this note'),
590 'courseid' => new external_value(PARAM_INT, 'id of the course'),
591 'userid' => new external_value(PARAM_INT, 'user id'),
592 'content' => new external_value(PARAM_RAW, 'the content text formated'),
593 'format' => new external_format_value('content'),
594 'created' => new external_value(PARAM_INT, 'time created (timestamp)'),
595 'lastmodified' => new external_value(PARAM_INT, 'time of last modification (timestamp)'),
596 'usermodified' => new external_value(PARAM_INT, 'user id of the creator of this note'),
597 'publishstate' => new external_value(PARAM_ALPHA, "state of the note (i.e. draft, public, site) ")
602 * Returns description of method result value
604 * @return external_description
605 * @since Moodle 2.9
607 public static function get_course_notes_returns() {
608 return new external_single_structure(
609 array(
610 'sitenotes' => new external_multiple_structure(
611 new external_single_structure(
612 self::get_note_structure() , ''
613 ), 'site notes', VALUE_OPTIONAL
615 'coursenotes' => new external_multiple_structure(
616 new external_single_structure(
617 self::get_note_structure() , ''
618 ), 'couse notes', VALUE_OPTIONAL
620 'personalnotes' => new external_multiple_structure(
621 new external_single_structure(
622 self::get_note_structure() , ''
623 ), 'personal notes', VALUE_OPTIONAL
625 'warnings' => new external_warnings()
626 ), 'notes'
631 * Returns description of method parameters
633 * @return external_function_parameters
634 * @since Moodle 2.9
636 public static function view_notes_parameters() {
637 return new external_function_parameters(
638 array(
639 'courseid' => new external_value(PARAM_INT, 'course id, 0 for notes at system level'),
640 'userid' => new external_value(PARAM_INT, 'user id, 0 means view all the user notes', VALUE_DEFAULT, 0)
646 * Simulates the web interface view of notes/index.php: trigger events
648 * @param int $courseid id of the course
649 * @param int $userid id of the user
650 * @return array of warnings and status result
651 * @since Moodle 2.9
652 * @throws moodle_exception
654 public static function view_notes($courseid, $userid = 0) {
655 global $CFG;
656 require_once($CFG->dirroot . "/notes/lib.php");
658 if (empty($CFG->enablenotes)) {
659 throw new moodle_exception('notesdisabled', 'notes');
662 $warnings = array();
663 $arrayparams = array(
664 'courseid' => $courseid,
665 'userid' => $userid
667 $params = self::validate_parameters(self::view_notes_parameters(), $arrayparams);
669 if (empty($params['courseid'])) {
670 $params['courseid'] = SITEID;
673 $course = get_course($params['courseid']);
675 if ($course->id == SITEID) {
676 $context = context_system::instance();
677 } else {
678 $context = context_course::instance($course->id);
681 // First of all, validate the context before do further permission checks.
682 self::validate_context($context);
683 require_capability('moodle/notes:view', $context);
685 if (!empty($params['userid'])) {
686 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
687 core_user::require_active_user($user);
689 if ($course->id != SITEID and !can_access_course($course, $user, '', true)) {
690 throw new moodle_exception('notenrolledprofile');
694 note_view($context, $params['userid']);
696 $result = array();
697 $result['status'] = true;
698 $result['warnings'] = $warnings;
699 return $result;
704 * Returns description of method result value
706 * @return external_description
707 * @since Moodle 2.9
709 public static function view_notes_returns() {
710 return new external_single_structure(
711 array(
712 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
713 'warnings' => new external_warnings()