[Summary view]

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

   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 report_insights;
  18  
  19  use core_external\external_api;
  20  use core_external\external_value;
  21  use core_external\external_single_structure;
  22  use core_external\external_multiple_structure;
  23  use core_external\external_function_parameters;
  24  use core_external\external_warnings;
  25  
  26  /**
  27   * This is the external API for this component.
  28   *
  29   * @package    report_insights
  30   * @copyright  2017 David Monllao {@link http://www.davidmonllao.com}
  31   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  32   */
  33  class external extends external_api {
  34  
  35      /**
  36       * set_notuseful_prediction parameters.
  37       *
  38       * @return external_function_parameters
  39       * @since  Moodle 3.4
  40       */
  41      public static function set_notuseful_prediction_parameters() {
  42          return new external_function_parameters(
  43              array(
  44                  'predictionid' => new external_value(PARAM_INT, 'The prediction id', VALUE_REQUIRED)
  45              )
  46          );
  47      }
  48  
  49      /**
  50       * Flags a prediction as fixed so no need to display it any more.
  51       *
  52       * @param int $predictionid
  53       * @return array an array of warnings and a boolean
  54       * @since  Moodle 3.4
  55       */
  56      public static function set_notuseful_prediction($predictionid) {
  57  
  58          $params = self::validate_parameters(self::set_notuseful_prediction_parameters(), array('predictionid' => $predictionid));
  59  
  60          list($model, $prediction, $context) = self::validate_prediction($params['predictionid']);
  61  
  62          $prediction->action_executed(\core_analytics\prediction::ACTION_NOT_USEFUL, $model->get_target());
  63  
  64          $success = true;
  65          return array('success' => $success, 'warnings' => array());
  66      }
  67  
  68      /**
  69       * set_notuseful_prediction return
  70       *
  71       * @return \core_external\external_description
  72       * @since  Moodle 3.4
  73       */
  74      public static function set_notuseful_prediction_returns() {
  75          return new external_single_structure(
  76              array(
  77                  'success' => new external_value(PARAM_BOOL, 'True if the prediction was successfully flagged as not useful.'),
  78                  'warnings' => new external_warnings(),
  79              )
  80          );
  81      }
  82  
  83      /**
  84       * Deprecated in favour of action_executed.
  85       */
  86      public static function set_notuseful_prediction_is_deprecated() {
  87          return true;
  88      }
  89  
  90      /**
  91       * set_fixed_prediction parameters.
  92       *
  93       * @return external_function_parameters
  94       * @since  Moodle 3.4
  95       */
  96      public static function set_fixed_prediction_parameters() {
  97          return new external_function_parameters(
  98              array(
  99                  'predictionid' => new external_value(PARAM_INT, 'The prediction id', VALUE_REQUIRED)
 100              )
 101          );
 102      }
 103  
 104      /**
 105       * Flags a prediction as fixed so no need to display it any more.
 106       *
 107       * @param int $predictionid
 108       * @return array an array of warnings and a boolean
 109       * @since  Moodle 3.4
 110       */
 111      public static function set_fixed_prediction($predictionid) {
 112  
 113          $params = self::validate_parameters(self::set_fixed_prediction_parameters(), array('predictionid' => $predictionid));
 114  
 115          list($model, $prediction, $context) = self::validate_prediction($params['predictionid']);
 116  
 117          $prediction->action_executed(\core_analytics\prediction::ACTION_FIXED, $model->get_target());
 118  
 119          $success = true;
 120          return array('success' => $success, 'warnings' => array());
 121      }
 122  
 123      /**
 124       * set_fixed_prediction return
 125       *
 126       * @return \core_external\external_description
 127       * @since  Moodle 3.4
 128       */
 129      public static function set_fixed_prediction_returns() {
 130          return new external_single_structure(
 131              array(
 132                  'success' => new external_value(PARAM_BOOL, 'True if the prediction was successfully flagged as fixed.'),
 133                  'warnings' => new external_warnings(),
 134              )
 135          );
 136      }
 137  
 138      /**
 139       * Deprecated in favour of action_executed.
 140       */
 141      public static function set_fixed_prediction_is_deprecated() {
 142          return true;
 143      }
 144  
 145      /**
 146       * action_executed parameters.
 147       *
 148       * @return external_function_parameters
 149       * @since  Moodle 3.8
 150       */
 151      public static function action_executed_parameters() {
 152          return new external_function_parameters (
 153              array(
 154                  'actionname' => new external_value(PARAM_ALPHANUMEXT, 'The name of the action', VALUE_REQUIRED),
 155                  'predictionids' => new external_multiple_structure(
 156                       new external_value(PARAM_INT, 'Prediction id', VALUE_REQUIRED),
 157                       'Array of prediction ids'
 158                  ),
 159              )
 160          );
 161      }
 162  
 163      /**
 164       * Stores an action executed over a group of predictions.
 165       *
 166       * @param  string   $actionname
 167       * @param  array    $predictionids
 168       * @return array an array of warnings and a boolean
 169       * @since  Moodle 3.8
 170       */
 171      public static function action_executed(string $actionname, array $predictionids) {
 172  
 173          $params = self::validate_parameters(self::action_executed_parameters(),
 174              array('actionname' => $actionname, 'predictionids' => $predictionids));
 175  
 176          foreach ($params['predictionids'] as $predictionid) {
 177              list($model, $prediction, $context) = self::validate_prediction($predictionid);
 178  
 179              // The method action_executed checks that the provided action is valid.
 180              $prediction->action_executed($actionname, $model->get_target());
 181          }
 182  
 183          return array('warnings' => array());
 184      }
 185  
 186      /**
 187       * action_executed return
 188       *
 189       * @return \core_external\external_description
 190       * @since  Moodle 3.8
 191       */
 192      public static function action_executed_returns() {
 193          return new external_single_structure(
 194              array(
 195                  'warnings' => new external_warnings(),
 196              )
 197          );
 198      }
 199  
 200      /**
 201       * Validates access to the prediction and returns it.
 202       *
 203       * @param int $predictionid
 204       * @return array array($model, $prediction, $context)
 205       */
 206      protected static function validate_prediction($predictionid) {
 207  
 208          list($model, $prediction, $context) = \core_analytics\manager::get_prediction($predictionid);
 209  
 210          self::validate_context($context);
 211  
 212          return array($model, $prediction, $context);
 213      }
 214  }