MDL-58835 report_insights: Not useful and ack prediction actions
[moodle.git] / report / insights / classes / external.php
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/>.
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  */
25 namespace report_insights;
27 defined('MOODLE_INTERNAL') || die();
29 require_once("$CFG->libdir/externallib.php");
31 use external_api;
32 use external_function_parameters;
33 use external_value;
34 use external_single_structure;
35 use external_warnings;
37 /**
38  * This is the external API for this component.
39  *
40  * @copyright  2017 David Monllao {@link http://www.davidmonllao.com}
41  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
42  */
43 class external extends external_api {
45     /**
46      * set_notuseful_prediction parameters.
47      *
48      * @return external_function_parameters
49      * @since  Moodle 3.4
50      */
51     public static function set_notuseful_prediction_parameters() {
52         return new external_function_parameters(
53             array(
54                 'predictionid' => new external_value(PARAM_INT, 'The prediction id', VALUE_REQUIRED)
55             )
56         );
57     }
59     /**
60      * Flags a prediction as fixed so no need to display it any more.
61      *
62      * @param int $predictionid
63      * @return array an array of warnings and a boolean
64      * @since  Moodle 3.4
65      */
66     public static function set_notuseful_prediction($predictionid) {
68         $params = self::validate_parameters(self::set_notuseful_prediction_parameters(), array('predictionid' => $predictionid));
70         list($model, $prediction, $context) = self::validate_prediction($params['predictionid']);
72         $prediction->action_executed(\core_analytics\prediction::ACTION_NOT_USEFUL, $model->get_target());
74         $success = true;
75         return array('success' => $success, 'warnings' => array());
76     }
78     /**
79      * set_notuseful_prediction return
80      *
81      * @return external_description
82      * @since  Moodle 3.4
83      */
84     public static function set_notuseful_prediction_returns() {
85         return new external_single_structure(
86             array(
87                 'success' => new external_value(PARAM_BOOL, 'True if the prediction was successfully flagged as not useful.'),
88                 'warnings' => new external_warnings(),
89             )
90         );
91     }
93     /**
94      * set_fixed_prediction parameters.
95      *
96      * @return external_function_parameters
97      * @since  Moodle 3.4
98      */
99     public static function set_fixed_prediction_parameters() {
100         return new external_function_parameters(
101             array(
102                 'predictionid' => new external_value(PARAM_INT, 'The prediction id', VALUE_REQUIRED)
103             )
104         );
105     }
107     /**
108      * Flags a prediction as fixed so no need to display it any more.
109      *
110      * @param int $predictionid
111      * @return array an array of warnings and a boolean
112      * @since  Moodle 3.4
113      */
114     public static function set_fixed_prediction($predictionid) {
116         $params = self::validate_parameters(self::set_fixed_prediction_parameters(), array('predictionid' => $predictionid));
118         list($model, $prediction, $context) = self::validate_prediction($params['predictionid']);
120         $prediction->action_executed(\core_analytics\prediction::ACTION_FIXED, $model->get_target());
122         $success = true;
123         return array('success' => $success, 'warnings' => array());
124     }
126     /**
127      * set_fixed_prediction return
128      *
129      * @return external_description
130      * @since  Moodle 3.4
131      */
132     public static function set_fixed_prediction_returns() {
133         return new external_single_structure(
134             array(
135                 'success' => new external_value(PARAM_BOOL, 'True if the prediction was successfully flagged as fixed.'),
136                 'warnings' => new external_warnings(),
137             )
138         );
139     }
141     /**
142      * Validates access to the prediction and returns it.
143      *
144      * @param int $predictionid
145      * @return array array($model, $prediction, $context)
146      */
147     protected static function validate_prediction($predictionid) {
149         list($model, $prediction, $context) = \core_analytics\manager::get_prediction($predictionid);
151         self::validate_context($context);
153         return array($model, $prediction, $context);
154     }