[Summary 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  namespace enrol_guest\external;
  18  
  19  use core_external\external_api;
  20  use core_external\external_function_parameters;
  21  use core_external\external_single_structure;
  22  use core_external\external_value;
  23  use core_external\external_warnings;
  24  use context_system;
  25  use moodle_exception;
  26  use core_text;
  27  use stdClass;
  28  
  29  /**
  30   * This is the external method validating a guest password.
  31   *
  32   * @package    enrol_guest
  33   * @since      Moodle 4.3
  34   * @copyright  2023 Juan Leyva <juan@moodle.com>
  35   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  36   */
  37  class validate_password extends external_api {
  38  
  39      /**
  40       * Webservice parameters.
  41       *
  42       * @return external_function_parameters
  43       */
  44      public static function execute_parameters(): external_function_parameters {
  45          return new external_function_parameters(
  46              [
  47                  'instanceid' => new external_value(PARAM_INT, 'instance id of guest enrolment plugin'),
  48                  'password' => new external_value(PARAM_RAW, 'the course password'),
  49              ]
  50          );
  51      }
  52  
  53      /**
  54       * Perform password validation.
  55       *
  56       * If password is correct: keep it as user preference.
  57       * If password is not correct: remove existing user preference (if any)
  58       *
  59       * @throws moodle_exception
  60       * @param  int $instanceid instance id of guest enrolment plugin
  61       * @param  string $password the course password
  62       * @return stdClass validation result info
  63       */
  64      public static function execute(int $instanceid, string $password): stdClass {
  65          global $CFG, $DB;
  66          require_once($CFG->libdir . '/enrollib.php');
  67  
  68          $params = external_api::validate_parameters(self::execute_parameters(), [
  69              'instanceid' => $instanceid,
  70              'password' => $password,
  71          ]);
  72          $warnings = [];
  73          $validated = false;
  74          $hint = '';
  75  
  76          // Retrieve guest enrolment plugin.
  77          $enrolplugin = enrol_get_plugin('guest');
  78          if (empty($enrolplugin)) {
  79              throw new moodle_exception('invaliddata', 'error');
  80          }
  81  
  82          self::validate_context(context_system::instance());
  83          $enrolinstance = $DB->get_record('enrol',
  84              ['id' => $params['instanceid'], 'status' => ENROL_INSTANCE_ENABLED], '*', MUST_EXIST);
  85          $course = $DB->get_record('course', ['id' => $enrolinstance->courseid], '*', MUST_EXIST);
  86  
  87          if (!\core_course_category::can_view_course_info($course) && !can_access_course($course)) {
  88              throw new moodle_exception('coursehidden');
  89          }
  90  
  91          if ($enrolinstance->password) {
  92              if ($params['password'] === $enrolinstance->password) {
  93                  $validated = true;
  94                  set_user_preference('enrol_guest_ws_password_' . $enrolinstance->id, $params['password']);
  95              } else {
  96                  // Always unset in case there was something stored.
  97                  unset_user_preference('enrol_guest_ws_password_' . $enrolinstance->id);
  98  
  99                  if ($enrolplugin->get_config('showhint')) {
 100                      $hint = core_text::substr($enrolinstance->password, 0, 1);
 101                      $hint = get_string('passwordinvalidhint', 'enrol_guest', $hint);
 102                  }
 103              }
 104          }
 105  
 106          $result = (object)[
 107              'validated' => $validated,
 108              'hint' => $hint,
 109              'warnings' => $warnings,
 110          ];
 111  
 112          return $result;
 113      }
 114  
 115      /**
 116       * Describes the return information.
 117       *
 118       * @return external_single_structure
 119       */
 120      public static function execute_returns(): external_single_structure {
 121          return new external_single_structure([
 122              'validated' => new external_value(PARAM_BOOL, 'Whether the password was successfully validated'),
 123              'hint' => new external_value(PARAM_RAW, 'Password hint (if enabled)', VALUE_OPTIONAL),
 124              'warnings' => new external_warnings(),
 125          ]);
 126      }
 127  }