[Summary view]

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