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_format_value('text', VALUE_DEFAULT),
  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)
  69      *
  70      * @param array $notes  An array of notes to create.
  71      * @return array (success infos and fail infos)
  72      * @since Moodle 2.2
  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', 'error');
 110             } else {
 111                 // Ensure the current user is allowed to run this function.
 112                 $context = context_course::instance($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.
 130                 $dbnote = new stdClass;
 131                 $dbnote->courseid = $note['courseid'];
 132                 $dbnote->userid = $note['userid'];
 133                 // Need to support 'html' and 'text' format values for backward compatibility.
 134                 switch (strtolower($note['format'])) {
 135                     case 'html':
 136                         $textformat = FORMAT_HTML;
 137                         break;
 138                     case 'text':
 139                         $textformat = FORMAT_PLAIN;
 140                     default:
 141                         $textformat = external_validate_format($note['format']);
 142                         break;
 143                 }
 144                 $dbnote->content = $note['text'];
 145                 $dbnote->format = $textformat;
 146
 147                 // Get the state ('personal', 'course', 'site').
 148                 switch ($note['publishstate']) {
 149                     case 'personal':
 150                         $dbnote->publishstate = NOTES_STATE_DRAFT;
 151                         break;
 152                     case 'course':
 153                         $dbnote->publishstate = NOTES_STATE_PUBLIC;
 154                         break;
 155                     case 'site':
 156                         $dbnote->publishstate = NOTES_STATE_SITE;
 157                         $dbnote->courseid = SITEID;
 158                         break;
 159                     default:
 160                         break;
 161                 }
 162
 163                 // TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once
 164                 if (note_save($dbnote)) { // Note_save attribut an id in case of success.
 165                     $success = $dbnote->id;
 166                 }
 167
 168                 $resultnote['noteid'] = $success;
 169             } else {
 170                 // WARNINGS: for backward compatibility we return this errormessage.
 171                 //          We should have thrown exceptions as these errors prevent results to be returned.
 172                 // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side .
 173                 $resultnote['noteid'] = -1;
 174                 $resultnote['errormessage'] = $errormessage;
 175             }
 176
 177             $resultnotes[] = $resultnote;
 178         }
 179
 180         return $resultnotes;
 181     }
 182
 183     /**
 184      * Returns description of method result value
 185      *
 186      * @return external_description
 187      * @since Moodle 2.2
 188      */
 189     public static function create_notes_returns() {
 190         return new external_multiple_structure(
 191             new external_single_structure(
 192                 array(
 193                     'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the note', VALUE_OPTIONAL),
 194                     'noteid' => new external_value(PARAM_INT, 'ID of the created note when successful, -1 when failed'),
 195                     'errormessage' => new external_value(PARAM_TEXT, 'error message - if failed', VALUE_OPTIONAL)
 196                 )
 197             )
 198         );
 199     }
 200
 201     /**
 202      * Returns description of delete_notes parameters
 203      *
 204      * @return external_function_parameters
 205      * @since Moodle 2.5
 206      */
 207     public static function delete_notes_parameters() {
 208         return new external_function_parameters(
 209             array(
 210                 "notes"=> new external_multiple_structure(
 211                     new external_value(PARAM_INT, 'ID of the note to be deleted'), 'Array of Note Ids to be deleted.'
 212                 )
 213             )
 214         );
 215     }
 216
 217     /**
 218      * Delete notes about users.
 219      * Note: code should be matching the /notes/delete.php checks.
 220      *
 221      * @param array $notes An array of ids for the notes to delete.
 222      * @return null
 223      * @since Moodle 2.5
 224      */
 225     public static function delete_notes($notes = array()) {
 226         global $CFG;
 227         require_once($CFG->dirroot . "/notes/lib.php");
 228
 229         $params = self::validate_parameters(self::delete_notes_parameters(), $notes);
 230
 231         // Check if note system is enabled.
 232         if (!$CFG->enablenotes) {
 233             throw new moodle_exception('notesdisabled', 'notes');
 234         }
 235         $warnings = array();
 236         foreach ($params['notes'] as $noteid) {
 237             $note = note_load($noteid);
 238             if (isset($note->id)) {
 239                 // Ensure the current user is allowed to run this function.
 240                 $context = context_course::instance($note->courseid);
 241                 self::validate_context($context);
 242                 require_capability('moodle/notes:manage', $context);
 243                 if (!note_delete($note)) {
 244                     $warnings[] = array(array('item' => 'note',
 245                                               'itemid' => $noteid,
 246                                               'warningcode' => 'savedfailed',
 247                                               'message' => 'Note could not be modified'));
 248                 }
 249             } else {
 250                 $warnings[] = array('item'=>'note', 'itemid'=>$noteid, 'warningcode'=>'badid', 'message'=>'Note does not exist');
 251             }
 252         }
 253         return $warnings;
 254     }
 255
 256     /**
 257      * Returns description of delete_notes result value.
 258      *
 259      * @return external_description
 260      * @since Moodle 2.5
 261      */
 262     public static function delete_notes_returns() {
 263         return  new external_warnings('item is always \'note\'',
 264                             'When errorcode is savedfailed the note could not be modified.' .
 265                             'When errorcode is badparam, an incorrect parameter was provided.' .
 266                             'When errorcode is badid, the note does not exist',
 267                             'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
 268
 269     }
 270
 271     /**
 272      * Returns description of get_notes parameters.
 273      *
 274      * @return external_function_parameters
 275      * @since Moodle 2.5
 276      */
 277     public static function get_notes_parameters() {
 278         return new external_function_parameters(
 279             array(
 280                 "notes"=> new external_multiple_structure(
 281                     new external_value(PARAM_INT, 'ID of the note to be retrieved'), 'Array of Note Ids to be retrieved.'
 282                 )
 283             )
 284         );
 285     }
 286
 287     /**
 288      * Get notes about users.
 289      *
 290      * @param array $notes An array of ids for the notes to retrieve.
 291      * @return null
 292      * @since Moodle 2.5
 293      */
 294     public static function get_notes($notes) {
 295         global $CFG;
 296         require_once($CFG->dirroot . "/notes/lib.php");
 297
 298         $params = self::validate_parameters(self::get_notes_parameters(), $notes);
 299         // Check if note system is enabled.
 300         if (!$CFG->enablenotes) {
 301             throw new moodle_exception('notesdisabled', 'notes');
 302         }
 303         $resultnotes = array();
 304         foreach ($params['notes'] as $noteid) {
 305             $resultnote = array();
 306
 307             $note = note_load($noteid);
 308             if (isset($note->id)) {
 309                 // Ensure the current user is allowed to run this function.
 310                 $context = context_course::instance($note->courseid);
 311                 self::validate_context($context);
 312                 require_capability('moodle/notes:view', $context);
 313                 list($gotnote['text'], $gotnote['format']) = external_format_text($note->content,
 314                                                                                   $note->format,
 315                                                                                   $context->id,
 316                                                                                   'notes',
 317                                                                                   '',
 318                                                                                   '');
 319                 $gotnote['noteid'] = $note->id;
 320                 $gotnote['userid'] = $note->userid;
 321                 $gotnote['publishstate'] = $note->publishstate;
 322                 $gotnote['courseid'] = $note->courseid;
 323                 $resultnotes["notes"][] = $gotnote;
 324             } else {
 325                 $resultnotes["warnings"][] = array('item' => 'note',
 326                                                    'itemid' => $noteid,
 327                                                    'warningcode' => 'badid',
 328                                                    'message' => 'Note does not exist');
 329             }
 330         }
 331         return $resultnotes;
 332     }
 333
 334     /**
 335      * Returns description of get_notes result value.
 336      *
 337      * @return external_description
 338      * @since Moodle 2.5
 339      */
 340     public static function get_notes_returns() {
 341         return new external_single_structure(
 342             array(
 343                 'notes' => new external_multiple_structure(
 344                     new external_single_structure(
 345                         array(
 346                             'noteid' => new external_value(PARAM_INT, 'id of the note', VALUE_OPTIONAL),
 347                             'userid' => new external_value(PARAM_INT, 'id of the user the note is about', VALUE_OPTIONAL),
 348                             'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\'', VALUE_OPTIONAL),
 349                             'courseid' => new external_value(PARAM_INT, 'course id of the note', VALUE_OPTIONAL),
 350                             'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML', VALUE_OPTIONAL),
 351                             'format' => new external_format_value('text', VALUE_OPTIONAL),
 352                         ), 'note'
 353                     )
 354                  ),
 355                  'warnings' => new external_warnings('item is always \'note\'',
 356                         'When errorcode is savedfailed the note could not be modified.' .
 357                         'When errorcode is badparam, an incorrect parameter was provided.' .
 358                         'When errorcode is badid, the note does not exist',
 359                         'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)')
 360             )
 361         );
 362     }
 363
 364     /**
 365      * Returns description of update_notes parameters.
 366      *
 367      * @return external_function_parameters
 368      * @since Moodle 2.5
 369      */
 370     public static function update_notes_parameters() {
 371         return new external_function_parameters(
 372             array(
 373                 'notes' => new external_multiple_structure(
 374                     new external_single_structure(
 375                         array(
 376                             'id' => new external_value(PARAM_INT, 'id of the note'),
 377                             'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\''),
 378                             'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML'),
 379                             'format' => new external_format_value('text', VALUE_DEFAULT),
 380                         )
 381                     ), "Array of Notes", VALUE_DEFAULT, array()
 382                 )
 383             )
 384         );
 385     }
 386
 387     /**
 388      * Update notes about users.
 389      *
 390      * @param array $notes An array of ids for the notes to update.
 391      * @return array fail infos.
 392      * @since Moodle 2.2
 393      */
 394     public static function update_notes($notes = array()) {
 395         global $CFG, $DB;
 396         require_once($CFG->dirroot . "/notes/lib.php");
 397
 398         $params = self::validate_parameters(self::update_notes_parameters(), array('notes' => $notes));
 399
 400         // Check if note system is enabled.
 401         if (!$CFG->enablenotes) {
 402             throw new moodle_exception('notesdisabled', 'notes');
 403         }
 404
 405         $warnings = array();
 406         foreach ($params['notes'] as $note) {
 407             $notedetails = note_load($note['id']);
 408             if (isset($notedetails->id)) {
 409                 // Ensure the current user is allowed to run this function.
 410                 $context = context_course::instance($notedetails->courseid);
 411                 self::validate_context($context);
 412                 require_capability('moodle/notes:manage', $context);
 413
 414                 $dbnote = new stdClass;
 415                 $dbnote->id = $note['id'];
 416                 $dbnote->content = $note['text'];
 417                 $dbnote->format = external_validate_format($note['format']);
 418                 // Get the state ('personal', 'course', 'site').
 419                 switch ($note['publishstate']) {
 420                     case 'personal':
 421                         $dbnote->publishstate = NOTES_STATE_DRAFT;
 422                         break;
 423                     case 'course':
 424                         $dbnote->publishstate = NOTES_STATE_PUBLIC;
 425                         break;
 426                     case 'site':
 427                         $dbnote->publishstate = NOTES_STATE_SITE;
 428                         $dbnote->courseid = SITEID;
 429                         break;
 430                     default:
 431                         $warnings[] = array('item' => 'note',
 432                                             'itemid' => $note["id"],
 433                                             'warningcode' => 'badparam',
 434                                             'message' => 'Provided publishstate incorrect');
 435                         break;
 436                 }
 437                 if (!note_save($dbnote)) {
 438                     $warnings[] = array('item' => 'note',
 439                                         'itemid' => $note["id"],
 440                                         'warningcode' => 'savedfailed',
 441                                         'message' => 'Note could not be modified');
 442                 }
 443             } else {
 444                 $warnings[] = array('item' => 'note',
 445                                     'itemid' => $note["id"],
 446                                     'warningcode' => 'badid',
 447                                     'message' => 'Note does not exist');
 448             }
 449         }
 450         return $warnings;
 451     }
 452
 453     /**
 454      * Returns description of update_notes result value.
 455      *
 456      * @return external_description
 457      * @since Moodle 2.5
 458      */
 459     public static function update_notes_returns() {
 460         return new external_warnings('item is always \'note\'',
 461                             'When errorcode is savedfailed the note could not be modified.' .
 462                             'When errorcode is badparam, an incorrect parameter was provided.' .
 463                             'When errorcode is badid, the note does not exist',
 464                             'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
 465     }
 466 }
 467
 468 /**
 469  * Deprecated notes external functions
 470  *
 471  * @package    core_notes
 472  * @copyright  2011 Jerome Mouneyrac
 473  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 474  * @since Moodle 2.1
 475  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 476  * @see core_notes_external
 477  */
 478 class moodle_notes_external extends external_api {
 479
 480     /**
 481      * Returns description of method parameters
 482      *
 483      * @return external_function_parameters
 484      * @since Moodle 2.1
 485      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 486      * @see core_notes_external::create_notes_parameters()
 487      */
 488     public static function create_notes_parameters() {
 489         return core_notes_external::create_notes_parameters();
 490     }
 491
 492     /**
 493      * Create notes about some users
 494      * Note: code should be matching the /notes/edit.php checks
 495      * and the /user/addnote.php checks. (they are similar cheks)
 496      *
 497      * @param array $notes  An array of notes to create.
 498      * @return array (success infos and fail infos)
 499      * @since Moodle 2.1
 500      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 501      * @see core_notes_external::create_notes()
 502      */
 503     public static function create_notes($notes = array()) {
 504         return core_notes_external::create_notes($notes);
 505     }
 506
 507     /**
 508      * Returns description of method result value
 509      *
 510      * @return external_description
 511      * @since Moodle 2.1
 512      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 513      * @see core_notes_external::create_notes_returns()
 514      */
 515     public static function create_notes_returns() {
 516         return core_notes_external::create_notes_returns();
 517     }
 518
 519 }