[Summary view] [Print] [Text view]

   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  }