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