[Summary view]

Differences Between: [Versions 39 and 310] [Versions 39 and 311] [Versions 39 and 400] [Versions 39 and 401] [Versions 39 and 402] [Versions 39 and 403]

   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   * Choice module external API
  19   *
  20   * @package    mod_choice
  21   * @category   external
  22   * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   * @since      Moodle 3.0
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  require_once($CFG->libdir . '/externallib.php');
  29  require_once($CFG->dirroot . '/mod/choice/lib.php');
  30  
  31  /**
  32   * Choice module external functions
  33   *
  34   * @package    mod_choice
  35   * @category   external
  36   * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
  37   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   * @since      Moodle 3.0
  39   */
  40  class mod_choice_external extends external_api {
  41  
  42      /**
  43       * Describes the parameters for get_choices_by_courses.
  44       *
  45       * @return external_function_parameters
  46       * @since Moodle 3.0
  47       */
  48      public static function get_choice_results_parameters() {
  49          return new external_function_parameters (array('choiceid' => new external_value(PARAM_INT, 'choice instance id')));
  50      }
  51      /**
  52       * Returns user's results for a specific choice
  53       * and a list of those users that did not answered yet.
  54       *
  55       * @param int $choiceid the choice instance id
  56       * @return array of responses details
  57       * @since Moodle 3.0
  58       */
  59      public static function get_choice_results($choiceid) {
  60          global $USER, $PAGE;
  61  
  62          $params = self::validate_parameters(self::get_choice_results_parameters(), array('choiceid' => $choiceid));
  63  
  64          if (!$choice = choice_get_choice($params['choiceid'])) {
  65              throw new moodle_exception("invalidcoursemodule", "error");
  66          }
  67          list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
  68  
  69          $context = context_module::instance($cm->id);
  70          self::validate_context($context);
  71  
  72          $groupmode = groups_get_activity_groupmode($cm);
  73          // Check if we have to include responses from inactive users.
  74          $onlyactive = $choice->includeinactive ? false : true;
  75          $users = choice_get_response_data($choice, $cm, $groupmode, $onlyactive);
  76          // Show those who haven't answered the question.
  77          if (!empty($choice->showunanswered)) {
  78              $choice->option[0] = get_string('notanswered', 'choice');
  79              $choice->maxanswers[0] = 0;
  80          }
  81          $results = prepare_choice_show_results($choice, $course, $cm, $users);
  82  
  83          $options = array();
  84          $fullnamecap = has_capability('moodle/site:viewfullnames', $context);
  85          foreach ($results->options as $optionid => $option) {
  86  
  87              $userresponses = array();
  88              $numberofuser = 0;
  89              $percentageamount = 0;
  90              if (property_exists($option, 'user') and
  91                  (has_capability('mod/choice:readresponses', $context) or choice_can_view_results($choice))) {
  92                  $numberofuser = count($option->user);
  93                  $percentageamount = ((float)$numberofuser / (float)$results->numberofuser) * 100.0;
  94                  if ($choice->publish) {
  95                      foreach ($option->user as $userresponse) {
  96                          $response = array();
  97                          $response['userid'] = $userresponse->id;
  98                          $response['fullname'] = fullname($userresponse, $fullnamecap);
  99  
 100                          $userpicture = new user_picture($userresponse);
 101                          $userpicture->size = 1; // Size f1.
 102                          $response['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
 103  
 104                          // Add optional properties.
 105                          foreach (array('answerid', 'timemodified') as $field) {
 106                              if (property_exists($userresponse, 'answerid')) {
 107                                  $response[$field] = $userresponse->$field;
 108                              }
 109                          }
 110                          $userresponses[] = $response;
 111                      }
 112                  }
 113              }
 114  
 115              $options[] = array('id'               => $optionid,
 116                                 'text'             => external_format_string($option->text, $context->id),
 117                                 'maxanswer'        => $option->maxanswer,
 118                                 'userresponses'    => $userresponses,
 119                                 'numberofuser'     => $numberofuser,
 120                                 'percentageamount' => $percentageamount
 121                                );
 122          }
 123  
 124          $warnings = array();
 125          return array(
 126              'options' => $options,
 127              'warnings' => $warnings
 128          );
 129      }
 130  
 131      /**
 132       * Describes the get_choice_results return value.
 133       *
 134       * @return external_single_structure
 135       * @since Moodle 3.0
 136       */
 137      public static function get_choice_results_returns() {
 138          return new external_single_structure(
 139              array(
 140                  'options' => new external_multiple_structure(
 141                      new external_single_structure(
 142                          array(
 143                              'id' => new external_value(PARAM_INT, 'choice instance id'),
 144                              'text' => new external_value(PARAM_RAW, 'text of the choice'),
 145                              'maxanswer' => new external_value(PARAM_INT, 'maximum number of answers'),
 146                              'userresponses' => new external_multiple_structure(
 147                                   new external_single_structure(
 148                                       array(
 149                                          'userid' => new external_value(PARAM_INT, 'user id'),
 150                                          'fullname' => new external_value(PARAM_NOTAGS, 'user full name'),
 151                                          'profileimageurl' => new external_value(PARAM_URL, 'profile user image url'),
 152                                          'answerid' => new external_value(PARAM_INT, 'answer id', VALUE_OPTIONAL),
 153                                          'timemodified' => new external_value(PARAM_INT, 'time of modification', VALUE_OPTIONAL),
 154                                       ), 'User responses'
 155                                   )
 156                              ),
 157                              'numberofuser' => new external_value(PARAM_INT, 'number of users answers'),
 158                              'percentageamount' => new external_value(PARAM_FLOAT, 'percentage of users answers')
 159                          ), 'Options'
 160                      )
 161                  ),
 162                  'warnings' => new external_warnings(),
 163              )
 164          );
 165      }
 166  
 167      /**
 168       * Describes the parameters for mod_choice_get_choice_options.
 169       *
 170       * @return external_function_parameters
 171       * @since Moodle 3.0
 172       */
 173      public static function get_choice_options_parameters() {
 174          return new external_function_parameters (array('choiceid' => new external_value(PARAM_INT, 'choice instance id')));
 175      }
 176  
 177      /**
 178       * Returns options for a specific choice
 179       *
 180       * @param int $choiceid the choice instance id
 181       * @return array of options details
 182       * @since Moodle 3.0
 183       */
 184      public static function get_choice_options($choiceid) {
 185          global $USER;
 186          $warnings = array();
 187          $params = self::validate_parameters(self::get_choice_options_parameters(), array('choiceid' => $choiceid));
 188  
 189          if (!$choice = choice_get_choice($params['choiceid'])) {
 190              throw new moodle_exception("invalidcoursemodule", "error");
 191          }
 192          list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
 193  
 194          $context = context_module::instance($cm->id);
 195          self::validate_context($context);
 196  
 197          require_capability('mod/choice:choose', $context);
 198  
 199          $groupmode = groups_get_activity_groupmode($cm);
 200          $onlyactive = $choice->includeinactive ? false : true;
 201          $allresponses = choice_get_response_data($choice, $cm, $groupmode, $onlyactive);
 202  
 203          $timenow = time();
 204          $choiceopen = true;
 205          $showpreview = false;
 206  
 207          if (!empty($choice->timeopen) && ($choice->timeopen > $timenow)) {
 208              $choiceopen = false;
 209              $warnings[1] = get_string("notopenyet", "choice", userdate($choice->timeopen));
 210              if ($choice->showpreview) {
 211                  $warnings[2] = get_string('previewonly', 'choice', userdate($choice->timeopen));
 212                  $showpreview = true;
 213              }
 214          }
 215          if (!empty($choice->timeclose) && ($timenow > $choice->timeclose)) {
 216              $choiceopen = false;
 217              $warnings[3] = get_string("expired", "choice", userdate($choice->timeclose));
 218          }
 219  
 220          $optionsarray = array();
 221  
 222          if ($choiceopen or $showpreview) {
 223  
 224              $options = choice_prepare_options($choice, $USER, $cm, $allresponses);
 225  
 226              foreach ($options['options'] as $option) {
 227                  $optionarr = array();
 228                  $optionarr['id']            = $option->attributes->value;
 229                  $optionarr['text']          = external_format_string($option->text, $context->id);
 230                  $optionarr['maxanswers']    = $option->maxanswers;
 231                  $optionarr['displaylayout'] = $option->displaylayout;
 232                  $optionarr['countanswers']  = $option->countanswers;
 233                  foreach (array('checked', 'disabled') as $field) {
 234                      if (property_exists($option->attributes, $field) and $option->attributes->$field == 1) {
 235                          $optionarr[$field] = 1;
 236                      } else {
 237                          $optionarr[$field] = 0;
 238                      }
 239                  }
 240                  // When showpreview is active, we show options as disabled.
 241                  if ($showpreview or ($optionarr['checked'] == 1 and !$choice->allowupdate)) {
 242                      $optionarr['disabled'] = 1;
 243                  }
 244                  $optionsarray[] = $optionarr;
 245              }
 246          }
 247          foreach ($warnings as $key => $message) {
 248              $warnings[$key] = array(
 249                  'item' => 'choice',
 250                  'itemid' => $cm->id,
 251                  'warningcode' => $key,
 252                  'message' => $message
 253              );
 254          }
 255          return array(
 256              'options' => $optionsarray,
 257              'warnings' => $warnings
 258          );
 259      }
 260  
 261      /**
 262       * Describes the get_choice_results return value.
 263       *
 264       * @return external_multiple_structure
 265       * @since Moodle 3.0
 266       */
 267      public static function get_choice_options_returns() {
 268          return new external_single_structure(
 269              array(
 270                  'options' => new external_multiple_structure(
 271                      new external_single_structure(
 272                          array(
 273                              'id' => new external_value(PARAM_INT, 'option id'),
 274                              'text' => new external_value(PARAM_RAW, 'text of the choice'),
 275                              'maxanswers' => new external_value(PARAM_INT, 'maximum number of answers'),
 276                              'displaylayout' => new external_value(PARAM_BOOL, 'true for orizontal, otherwise vertical'),
 277                              'countanswers' => new external_value(PARAM_INT, 'number of answers'),
 278                              'checked' => new external_value(PARAM_BOOL, 'we already answered'),
 279                              'disabled' => new external_value(PARAM_BOOL, 'option disabled'),
 280                              )
 281                      ), 'Options'
 282                  ),
 283                  'warnings' => new external_warnings(),
 284              )
 285          );
 286      }
 287  
 288      /**
 289       * Describes the parameters for submit_choice_response.
 290       *
 291       * @return external_function_parameters
 292       * @since Moodle 3.0
 293       */
 294      public static function submit_choice_response_parameters() {
 295          return new external_function_parameters (
 296              array(
 297                  'choiceid' => new external_value(PARAM_INT, 'choice instance id'),
 298                  'responses' => new external_multiple_structure(
 299                      new external_value(PARAM_INT, 'answer id'),
 300                      'Array of response ids'
 301                  ),
 302              )
 303          );
 304      }
 305  
 306      /**
 307       * Submit choice responses
 308       *
 309       * @param int $choiceid the choice instance id
 310       * @param array $responses the response ids
 311       * @return array answers information and warnings
 312       * @since Moodle 3.0
 313       */
 314      public static function submit_choice_response($choiceid, $responses) {
 315          global $USER;
 316  
 317          $warnings = array();
 318          $params = self::validate_parameters(self::submit_choice_response_parameters(),
 319                                              array(
 320                                                  'choiceid' => $choiceid,
 321                                                  'responses' => $responses
 322                                              ));
 323  
 324          if (!$choice = choice_get_choice($params['choiceid'])) {
 325              throw new moodle_exception("invalidcoursemodule", "error");
 326          }
 327          list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
 328  
 329          $context = context_module::instance($cm->id);
 330          self::validate_context($context);
 331  
 332          require_capability('mod/choice:choose', $context);
 333  
 334          $timenow = time();
 335          if (!empty($choice->timeopen) && ($choice->timeopen > $timenow)) {
 336              throw new moodle_exception("notopenyet", "choice", '', userdate($choice->timeopen));
 337          } else if (!empty($choice->timeclose) && ($timenow > $choice->timeclose)) {
 338              throw new moodle_exception("expired", "choice", '', userdate($choice->timeclose));
 339          }
 340  
 341          if (!choice_get_my_response($choice) or $choice->allowupdate) {
 342              // When a single response is given, we convert the array to a simple variable
 343              // in order to avoid choice_user_submit_response to check with allowmultiple even
 344              // for a single response.
 345              if (count($params['responses']) == 1) {
 346                  $params['responses'] = reset($params['responses']);
 347              }
 348              choice_user_submit_response($params['responses'], $choice, $USER->id, $course, $cm);
 349          } else {
 350              throw new moodle_exception('missingrequiredcapability', 'webservice', '', 'allowupdate');
 351          }
 352          $answers = choice_get_my_response($choice);
 353  
 354          return array(
 355              'answers' => $answers,
 356              'warnings' => $warnings
 357          );
 358      }
 359  
 360      /**
 361       * Describes the submit_choice_response return value.
 362       *
 363       * @return external_multiple_structure
 364       * @since Moodle 3.0
 365       */
 366      public static function submit_choice_response_returns() {
 367          return new external_single_structure(
 368              array(
 369                  'answers' => new external_multiple_structure(
 370                       new external_single_structure(
 371                           array(
 372                               'id'           => new external_value(PARAM_INT, 'answer id'),
 373                               'choiceid'     => new external_value(PARAM_INT, 'choiceid'),
 374                               'userid'       => new external_value(PARAM_INT, 'user id'),
 375                               'optionid'     => new external_value(PARAM_INT, 'optionid'),
 376                               'timemodified' => new external_value(PARAM_INT, 'time of last modification')
 377                           ), 'Answers'
 378                       )
 379                  ),
 380                  'warnings' => new external_warnings(),
 381              )
 382          );
 383      }
 384  
 385      /**
 386       * Returns description of method parameters
 387       *
 388       * @return external_function_parameters
 389       * @since Moodle 3.0
 390       */
 391      public static function view_choice_parameters() {
 392          return new external_function_parameters(
 393              array(
 394                  'choiceid' => new external_value(PARAM_INT, 'choice instance id')
 395              )
 396          );
 397      }
 398  
 399      /**
 400       * Trigger the course module viewed event and update the module completion status.
 401       *
 402       * @param int $choiceid the choice instance id
 403       * @return array of warnings and status result
 404       * @since Moodle 3.0
 405       * @throws moodle_exception
 406       */
 407      public static function view_choice($choiceid) {
 408          global $CFG;
 409  
 410          $params = self::validate_parameters(self::view_choice_parameters(),
 411                                              array(
 412                                                  'choiceid' => $choiceid
 413                                              ));
 414          $warnings = array();
 415  
 416          // Request and permission validation.
 417          if (!$choice = choice_get_choice($params['choiceid'])) {
 418              throw new moodle_exception("invalidcoursemodule", "error");
 419          }
 420          list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
 421  
 422          $context = context_module::instance($cm->id);
 423          self::validate_context($context);
 424  
 425          // Trigger course_module_viewed event and completion.
 426          choice_view($choice, $course, $cm, $context);
 427  
 428          $result = array();
 429          $result['status'] = true;
 430          $result['warnings'] = $warnings;
 431          return $result;
 432      }
 433  
 434      /**
 435       * Returns description of method result value
 436       *
 437       * @return external_description
 438       * @since Moodle 3.0
 439       */
 440      public static function view_choice_returns() {
 441          return new external_single_structure(
 442              array(
 443                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 444                  'warnings' => new external_warnings()
 445              )
 446          );
 447      }
 448  
 449      /**
 450       * Describes the parameters for get_choices_by_courses.
 451       *
 452       * @return external_function_parameters
 453       * @since Moodle 3.0
 454       */
 455      public static function get_choices_by_courses_parameters() {
 456          return new external_function_parameters (
 457              array(
 458                  'courseids' => new external_multiple_structure(
 459                      new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
 460                  ),
 461              )
 462          );
 463      }
 464  
 465      /**
 466       * Returns a list of choices in a provided list of courses,
 467       * if no list is provided all choices that the user can view will be returned.
 468       *
 469       * @param array $courseids the course ids
 470       * @return array of choices details
 471       * @since Moodle 3.0
 472       */
 473      public static function get_choices_by_courses($courseids = array()) {
 474          global $CFG;
 475  
 476          $returnedchoices = array();
 477          $warnings = array();
 478  
 479          $params = self::validate_parameters(self::get_choices_by_courses_parameters(), array('courseids' => $courseids));
 480  
 481          $courses = array();
 482          if (empty($params['courseids'])) {
 483              $courses = enrol_get_my_courses();
 484              $params['courseids'] = array_keys($courses);
 485          }
 486  
 487          // Ensure there are courseids to loop through.
 488          if (!empty($params['courseids'])) {
 489  
 490              list($courses, $warnings) = external_util::validate_courses($params['courseids'], $courses);
 491  
 492              // Get the choices in this course, this function checks users visibility permissions.
 493              // We can avoid then additional validate_context calls.
 494              $choices = get_all_instances_in_courses("choice", $courses);
 495              foreach ($choices as $choice) {
 496                  $context = context_module::instance($choice->coursemodule);
 497                  // Entry to return.
 498                  $choicedetails = array();
 499                  // First, we return information that any user can see in the web interface.
 500                  $choicedetails['id'] = $choice->id;
 501                  $choicedetails['coursemodule'] = $choice->coursemodule;
 502                  $choicedetails['course'] = $choice->course;
 503                  $choicedetails['name']  = external_format_string($choice->name, $context->id);
 504                  // Format intro.
 505                  $options = array('noclean' => true);
 506                  list($choicedetails['intro'], $choicedetails['introformat']) =
 507                      external_format_text($choice->intro, $choice->introformat, $context->id, 'mod_choice', 'intro', null, $options);
 508                  $choicedetails['introfiles'] = external_util::get_area_files($context->id, 'mod_choice', 'intro', false, false);
 509  
 510                  if (has_capability('mod/choice:choose', $context)) {
 511                      $choicedetails['publish']  = $choice->publish;
 512                      $choicedetails['showresults']  = $choice->showresults;
 513                      $choicedetails['showpreview']  = $choice->showpreview;
 514                      $choicedetails['timeopen']  = $choice->timeopen;
 515                      $choicedetails['timeclose']  = $choice->timeclose;
 516                      $choicedetails['display']  = $choice->display;
 517                      $choicedetails['allowupdate']  = $choice->allowupdate;
 518                      $choicedetails['allowmultiple']  = $choice->allowmultiple;
 519                      $choicedetails['limitanswers']  = $choice->limitanswers;
 520                      $choicedetails['showunanswered']  = $choice->showunanswered;
 521                      $choicedetails['includeinactive']  = $choice->includeinactive;
 522                  }
 523  
 524                  if (has_capability('moodle/course:manageactivities', $context)) {
 525                      $choicedetails['timemodified']  = $choice->timemodified;
 526                      $choicedetails['completionsubmit']  = $choice->completionsubmit;
 527                      $choicedetails['section']  = $choice->section;
 528                      $choicedetails['visible']  = $choice->visible;
 529                      $choicedetails['groupmode']  = $choice->groupmode;
 530                      $choicedetails['groupingid']  = $choice->groupingid;
 531                  }
 532                  $returnedchoices[] = $choicedetails;
 533              }
 534          }
 535          $result = array();
 536          $result['choices'] = $returnedchoices;
 537          $result['warnings'] = $warnings;
 538          return $result;
 539      }
 540  
 541      /**
 542       * Describes the mod_choice_get_choices_by_courses return value.
 543       *
 544       * @return external_single_structure
 545       * @since Moodle 3.0
 546       */
 547      public static function get_choices_by_courses_returns() {
 548          return new external_single_structure(
 549              array(
 550                  'choices' => new external_multiple_structure(
 551                      new external_single_structure(
 552                          array(
 553                              'id' => new external_value(PARAM_INT, 'Choice instance id'),
 554                              'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
 555                              'course' => new external_value(PARAM_INT, 'Course id'),
 556                              'name' => new external_value(PARAM_RAW, 'Choice name'),
 557                              'intro' => new external_value(PARAM_RAW, 'The choice intro'),
 558                              'introformat' => new external_format_value('intro'),
 559                              'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
 560                              'publish' => new external_value(PARAM_BOOL, 'If choice is published', VALUE_OPTIONAL),
 561                              'showresults' => new external_value(PARAM_INT, '0 never, 1 after answer, 2 after close, 3 always',
 562                                                                  VALUE_OPTIONAL),
 563                              'display' => new external_value(PARAM_INT, 'Display mode (vertical, horizontal)', VALUE_OPTIONAL),
 564                              'allowupdate' => new external_value(PARAM_BOOL, 'Allow update', VALUE_OPTIONAL),
 565                              'allowmultiple' => new external_value(PARAM_BOOL, 'Allow multiple choices', VALUE_OPTIONAL),
 566                              'showunanswered' => new external_value(PARAM_BOOL, 'Show users who not answered yet', VALUE_OPTIONAL),
 567                              'includeinactive' => new external_value(PARAM_BOOL, 'Include inactive users', VALUE_OPTIONAL),
 568                              'limitanswers' => new external_value(PARAM_BOOL, 'Limit unswers', VALUE_OPTIONAL),
 569                              'timeopen' => new external_value(PARAM_INT, 'Date of opening validity', VALUE_OPTIONAL),
 570                              'timeclose' => new external_value(PARAM_INT, 'Date of closing validity', VALUE_OPTIONAL),
 571                              'showpreview' => new external_value(PARAM_BOOL, 'Show preview before timeopen', VALUE_OPTIONAL),
 572                              'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL),
 573                              'completionsubmit' => new external_value(PARAM_BOOL, 'Completion on user submission', VALUE_OPTIONAL),
 574                              'section' => new external_value(PARAM_INT, 'Course section id', VALUE_OPTIONAL),
 575                              'visible' => new external_value(PARAM_BOOL, 'Visible', VALUE_OPTIONAL),
 576                              'groupmode' => new external_value(PARAM_INT, 'Group mode', VALUE_OPTIONAL),
 577                              'groupingid' => new external_value(PARAM_INT, 'Group id', VALUE_OPTIONAL),
 578                          ), 'Choices'
 579                      )
 580                  ),
 581                  'warnings' => new external_warnings(),
 582              )
 583          );
 584      }
 585  
 586      /**
 587       * Describes the parameters for delete_choice_responses.
 588       *
 589       * @return external_function_parameters
 590       * @since Moodle 3.0
 591       */
 592      public static function delete_choice_responses_parameters() {
 593          return new external_function_parameters (
 594              array(
 595                  'choiceid' => new external_value(PARAM_INT, 'choice instance id'),
 596                  'responses' => new external_multiple_structure(
 597                      new external_value(PARAM_INT, 'response id'),
 598                      'Array of response ids, empty for deleting all the current user responses.',
 599                      VALUE_DEFAULT,
 600                      array()
 601                  ),
 602              )
 603          );
 604      }
 605  
 606      /**
 607       * Delete the given submitted responses in a choice
 608       *
 609       * @param int $choiceid the choice instance id
 610       * @param array $responses the response ids,  empty for deleting all the current user responses
 611       * @return array status information and warnings
 612       * @throws moodle_exception
 613       * @since Moodle 3.0
 614       */
 615      public static function delete_choice_responses($choiceid, $responses = array()) {
 616  
 617          $status = false;
 618          $warnings = array();
 619          $params = self::validate_parameters(self::delete_choice_responses_parameters(),
 620                                              array(
 621                                                  'choiceid' => $choiceid,
 622                                                  'responses' => $responses
 623                                              ));
 624  
 625          if (!$choice = choice_get_choice($params['choiceid'])) {
 626              throw new moodle_exception("invalidcoursemodule", "error");
 627          }
 628          list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
 629  
 630          $context = context_module::instance($cm->id);
 631          self::validate_context($context);
 632  
 633          require_capability('mod/choice:choose', $context);
 634  
 635          $candeleteall = has_capability('mod/choice:deleteresponses', $context);
 636          if ($candeleteall || $choice->allowupdate) {
 637  
 638              // Check if we can delete our own responses.
 639              if (!$candeleteall) {
 640                  $timenow = time();
 641                  if (!empty($choice->timeclose) && ($timenow > $choice->timeclose)) {
 642                      throw new moodle_exception("expired", "choice", '', userdate($choice->timeclose));
 643                  }
 644              }
 645  
 646              if (empty($params['responses'])) {
 647                  // No responses indicated so delete only my responses.
 648                  $todelete = array_keys(choice_get_my_response($choice));
 649              } else {
 650                  // Fill an array with the responses that can be deleted for this choice.
 651                  if ($candeleteall) {
 652                      // Teacher/managers can delete any.
 653                      $allowedresponses = array_keys(choice_get_all_responses($choice));
 654                  } else {
 655                      // Students can delete only their own responses.
 656                      $allowedresponses = array_keys(choice_get_my_response($choice));
 657                  }
 658  
 659                  $todelete = array();
 660                  foreach ($params['responses'] as $response) {
 661                      if (!in_array($response, $allowedresponses)) {
 662                          $warnings[] = array(
 663                              'item' => 'response',
 664                              'itemid' => $response,
 665                              'warningcode' => 'nopermissions',
 666                              'message' => 'Invalid response id, the response does not exist or you are not allowed to delete it.'
 667                          );
 668                      } else {
 669                          $todelete[] = $response;
 670                      }
 671                  }
 672              }
 673  
 674              $status = choice_delete_responses($todelete, $choice, $cm, $course);
 675          } else {
 676              // The user requires the capability to delete responses.
 677              throw new required_capability_exception($context, 'mod/choice:deleteresponses', 'nopermissions', '');
 678          }
 679  
 680          return array(
 681              'status' => $status,
 682              'warnings' => $warnings
 683          );
 684      }
 685  
 686      /**
 687       * Describes the delete_choice_responses return value.
 688       *
 689       * @return external_multiple_structure
 690       * @since Moodle 3.0
 691       */
 692      public static function delete_choice_responses_returns() {
 693          return new external_single_structure(
 694              array(
 695                  'status' => new external_value(PARAM_BOOL, 'status, true if everything went right'),
 696                  'warnings' => new external_warnings(),
 697              )
 698          );
 699      }
 700  
 701  }