notes/externallib.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
  18 /**
  19  * External notes API
  20  *
  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
  25  */
  26
  27 require_once("$CFG->libdir/externallib.php");
  28
  29 /**
  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
  37  */
  38 class core_notes_external extends external_api {
  39
  40     /**
  41      * Returns description of method parameters
  42      *
  43      * @return external_function_parameters
  44      * @since Moodle 2.2
  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_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),
  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)
  73      *
  74      * @param array $notes  An array of notes to create.
  75      * @return array (success infos and fail infos)
  76      * @since Moodle 2.2
  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', 'error');
 114             } else {
 115                 // Ensure the current user is allowed to run this function
 116                 $context = context_course::instance($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
 134                 $dbnote = new stdClass;
 135                 $dbnote->courseid = $note['courseid'];
 136                 $dbnote->userid = $note['userid'];
 137                 // Need to support 'html' and 'text' format values for backward compatibility.
 138                 switch (strtolower($note['format'])) {
 139                     case 'html':
 140                         $textformat = FORMAT_HTML;
 141                         break;
 142                     case 'text':
 143                         $textformat = FORMAT_PLAIN;
 144                     default:
 145                         $textformat = external_validate_format($note['format']);
 146                         break;
 147                 }
 148                 $dbnote->content = $note['text'];
 149                 $dbnote->format = $textformat;
 150
 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                 }
 166
 167                 //TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once
 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 {
 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 .
 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
 192      *
 193      * @return external_description
 194      * @since Moodle 2.2
 195      */
 196     public static function create_notes_returns() {
 197         return new external_multiple_structure(
 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)
 203                 )
 204             )
 205         );
 206     }
 207
 208 }
 209
 210 /**
 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
 220  */
 221 class moodle_notes_external extends external_api {
 222
 223     /**
 224      * Returns description of method parameters
 225      *
 226      * @return external_function_parameters
 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()
 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)
 240      *
 241      * @param array $notes  An array of notes to create.
 242      * @return array (success infos and fail infos)
 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()
 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
 254      *
 255      * @return external_description
 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()
 260      */
 261     public static function create_notes_returns() {
 262         return core_notes_external::create_notes_returns();
 263     }
 264
 265 }