Merge branch 'MDL-33577' of git://github.com/timhunt/moodle
[moodle.git] / notes / externallib.php
CommitLineData
8d46dabb 1<?php
8d46dabb
JM
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
4615817d 17
8d46dabb
JM
18/**
19 * External notes API
20 *
4615817d
JM
21 * @package core_notes
22 * @category external
23 * @copyright 2011 Jerome Mouneyrac
8d46dabb
JM
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
4615817d 26
8d46dabb
JM
27require_once("$CFG->libdir/externallib.php");
28
5d1017e1 29/**
4615817d
JM
30 * Notes external functions
31 *
32 * @package core_notes
33 * @category external
34 * @copyright 2011 Jerome Mouneyrac
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 * @since Moodle 2.2
5d1017e1
JM
37 */
38class core_notes_external extends external_api {
8d46dabb
JM
39
40 /**
41 * Returns description of method parameters
4615817d 42 *
8d46dabb 43 * @return external_function_parameters
4615817d 44 * @since Moodle 2.2
8d46dabb
JM
45 */
46 public static function create_notes_parameters() {
47 return new external_function_parameters(
48 array(
49 'notes' => new external_multiple_structure(
50 new external_single_structure(
51 array(
52 'userid' => new external_value(PARAM_INT, 'id of the user the note is about'),
53 'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\''),
54 '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)'),
55 'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML'),
93ce0e82
JM
56 'format' => new external_value(PARAM_ALPHANUMEXT, // For backward compatibility it can not be PARAM_INT, so we don't use external_format_value.
57 'text format (' . FORMAT_HTML . ' = HTML, '
58 . FORMAT_MOODLE . ' = MOODLE, '
59 . FORMAT_PLAIN . ' = PLAIN or '
60 . FORMAT_MARKDOWN . ' = MARKDOWN)', VALUE_DEFAULT, FORMAT_HTML),
8d46dabb
JM
61 '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),
62 )
63 )
64 )
65 )
66 );
67 }
68
69 /**
70 * Create notes about some users
71 * Note: code should be matching the /notes/edit.php checks
72 * and the /user/addnote.php checks. (they are similar cheks)
4615817d 73 *
0373264c 74 * @param array $notes An array of notes to create.
8d46dabb 75 * @return array (success infos and fail infos)
4615817d 76 * @since Moodle 2.2
8d46dabb
JM
77 */
78 public static function create_notes($notes = array()) {
79 global $CFG, $DB;
80 require_once($CFG->dirroot . "/notes/lib.php");
81
82 $params = self::validate_parameters(self::create_notes_parameters(), array('notes' => $notes));
83
84 //check if note system is enabled
85 if (!$CFG->enablenotes) {
86 throw new moodle_exception('notesdisabled', 'notes');
87 }
88
89 //retrieve all courses
90 $courseids = array();
91 foreach($params['notes'] as $note) {
92 $courseids[] = $note['courseid'];
93 }
94 $courses = $DB->get_records_list("course", "id", $courseids);
95
96 //retrieve all users of the notes
97 $userids = array();
98 foreach($params['notes'] as $note) {
99 $userids[] = $note['userid'];
100 }
101 list($sqluserids, $sqlparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'userid_');
102 $users = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
103
104 $resultnotes = array();
105 foreach ($params['notes'] as $note) {
106
107 $success = true;
108 $resultnote = array(); //the infos about the success of the operation
109
110 //check the course exists
111 if (empty($courses[$note['courseid']])) {
112 $success = false;
113 $errormessage = get_string('invalidcourseid', 'notes', $note['courseid']);
114 } else {
115 // Ensure the current user is allowed to run this function
116 $context = get_context_instance(CONTEXT_COURSE, $note['courseid']);
117 self::validate_context($context);
118 require_capability('moodle/notes:manage', $context);
119 }
120
121 //check the user exists
122 if (empty($users[$note['userid']])) {
123 $success = false;
124 $errormessage = get_string('invaliduserid', 'notes', $note['userid']);
125 }
126
127 //build the resultnote
128 if (isset($note['clientnoteid'])) {
129 $resultnote['clientnoteid'] = $note['clientnoteid'];
130 }
131
132 if ($success) {
133 //now we can create the note
0373264c 134 $dbnote = new stdClass;
8d46dabb 135 $dbnote->courseid = $note['courseid'];
0373264c 136 $dbnote->userid = $note['userid'];
93ce0e82 137 // Need to support 'html' and 'text' format values for backward compatibility.
8d46dabb
JM
138 switch (strtolower($note['format'])) {
139 case 'html':
93ce0e82 140 $textformat = FORMAT_HTML;
8d46dabb
JM
141 break;
142 case 'text':
93ce0e82 143 $textformat = FORMAT_PLAIN;
8d46dabb 144 default:
93ce0e82 145 $textformat = external_validate_format($note['format']);
8d46dabb
JM
146 break;
147 }
93ce0e82
JM
148 $dbnote->content = $note['text'];
149 $dbnote->format = $textformat;
8d46dabb 150
8d46dabb
JM
151 //get the state ('personal', 'course', 'site')
152 switch ($note['publishstate']) {
153 case 'personal':
154 $dbnote->publishstate = NOTES_STATE_DRAFT;
155 break;
156 case 'course':
157 $dbnote->publishstate = NOTES_STATE_PUBLIC;
158 break;
159 case 'site':
160 $dbnote->publishstate = NOTES_STATE_SITE;
161 $dbnote->courseid = SITEID;
162 break;
163 default:
164 break;
165 }
8d46dabb 166
4615817d 167 //TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once
8d46dabb
JM
168 if (note_save($dbnote)) { //note_save attribut an id in case of success
169 add_to_log($dbnote->courseid, 'notes', 'add',
170 'index.php?course='.$dbnote->courseid.'&amp;user='.$dbnote->userid
171 . '#note-' . $dbnote->id , 'add note');
172 $success = $dbnote->id;
173 }
174
175 $resultnote['noteid'] = $success;
176 } else {
93ce0e82
JM
177 // WARNINGS: for backward compatibility we return this errormessage.
178 // We should have thrown exceptions as these errors prevent results to be returned.
179 // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side .
8d46dabb
JM
180 $resultnote['noteid'] = -1;
181 $resultnote['errormessage'] = $errormessage;
182 }
183
184 $resultnotes[] = $resultnote;
185 }
186
187 return $resultnotes;
188 }
189
190 /**
191 * Returns description of method result value
4615817d 192 *
8d46dabb 193 * @return external_description
4615817d 194 * @since Moodle 2.2
8d46dabb
JM
195 */
196 public static function create_notes_returns() {
197 return new external_multiple_structure(
0373264c
SH
198 new external_single_structure(
199 array(
200 'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the note', VALUE_OPTIONAL),
201 'noteid' => new external_value(PARAM_INT, 'test this to know if it success: id of the created note when successed, -1 when failed'),
202 'errormessage' => new external_value(PARAM_TEXT, 'error message - if failed', VALUE_OPTIONAL)
8d46dabb 203 )
0373264c 204 )
8d46dabb
JM
205 );
206 }
207
208}
5d1017e1
JM
209
210/**
4615817d
JM
211 * Deprecated notes external functions
212 *
213 * @package core_notes
214 * @copyright 2011 Jerome Mouneyrac
215 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
216 * @since Moodle 2.1
217 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
218 * @todo MDL-31194 This will be deleted in Moodle 2.5.
219 * @see core_notes_external
5d1017e1
JM
220 */
221class moodle_notes_external extends external_api {
222
223 /**
224 * Returns description of method parameters
4615817d 225 *
5d1017e1 226 * @return external_function_parameters
4615817d
JM
227 * @since Moodle 2.1
228 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
229 * @todo MDL-31194 This will be deleted in Moodle 2.5.
230 * @see core_notes_external::create_notes_parameters()
5d1017e1
JM
231 */
232 public static function create_notes_parameters() {
233 return core_notes_external::create_notes_parameters();
234 }
235
236 /**
237 * Create notes about some users
238 * Note: code should be matching the /notes/edit.php checks
239 * and the /user/addnote.php checks. (they are similar cheks)
4615817d 240 *
5d1017e1
JM
241 * @param array $notes An array of notes to create.
242 * @return array (success infos and fail infos)
4615817d
JM
243 * @since Moodle 2.1
244 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
245 * @todo MDL-31194 This will be deleted in Moodle 2.5.
246 * @see core_notes_external::create_notes()
5d1017e1
JM
247 */
248 public static function create_notes($notes = array()) {
249 return core_notes_external::create_notes($notes);
250 }
251
252 /**
253 * Returns description of method result value
4615817d 254 *
5d1017e1 255 * @return external_description
4615817d
JM
256 * @since Moodle 2.1
257 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
258 * @todo MDL-31194 This will be deleted in Moodle 2.5.
259 * @see core_notes_external::create_notes_returns()
5d1017e1
JM
260 */
261 public static function create_notes_returns() {
262 return core_notes_external::create_notes_returns();
263 }
264
265}