MDL-62342 privacy: Use singular/plural form in labels
[moodle.git] / admin / tool / policy / 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  * Class containing the external API functions functions for the Policy tool.
19  *
20  * @package    tool_policy
21  * @copyright  2018 Sara Arjona (sara@moodle.com)
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace tool_policy;
27 defined('MOODLE_INTERNAL') || die();
29 use coding_exception;
30 use context_system;
31 use context_user;
32 use core\invalid_persistent_exception;
33 use dml_exception;
34 use external_api;
35 use external_description;
36 use external_function_parameters;
37 use external_single_structure;
38 use external_value;
39 use external_warnings;
40 use invalid_parameter_exception;
41 use moodle_exception;
42 use restricted_context_exception;
43 use tool_policy\api;
44 use tool_policy\form\accept_policy;
46 /**
47  * Class external.
48  *
49  * The external API for the Policy tool.
50  *
51  * @copyright   2018 Sara Arjona (sara@moodle.com)
52  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
53  */
54 class external extends external_api {
56     /**
57      * Parameter description for get_policy_version_parameters().
58      *
59      * @return external_function_parameters
60      */
61     public static function get_policy_version_parameters() {
62         return new external_function_parameters([
63             'versionid' => new external_value(PARAM_INT, 'The policy version ID', VALUE_REQUIRED),
64             'behalfid' => new external_value(PARAM_INT, 'The id of user on whose behalf the user is viewing the policy',
65                 VALUE_DEFAULT, 0)
66         ]);
67     }
69     /**
70      * Fetch the details of a policy version.
71      *
72      * @param int $versionid The policy version ID.
73      * @param int $behalfid The id of user on whose behalf the user is viewing the policy.
74      * @return array
75      * @throws coding_exception
76      * @throws dml_exception
77      * @throws invalid_parameter_exception
78      * @throws restricted_context_exception
79      * @throws moodle_exception
80      */
81     public static function get_policy_version($versionid, $behalfid = null) {
82         global $PAGE;
84         $result = [];
85         $warnings = [];
86         $params = external_api::validate_parameters(self::get_policy_version_parameters(), [
87             'versionid' => $versionid,
88             'behalfid' => $behalfid
89         ]);
90         $versionid = $params['versionid'];
91         $behalfid = $params['behalfid'];
93         $context = context_system::instance();
94         $PAGE->set_context($context);
96         try {
97             // Validate if the user has access to the policy version.
98             $version = api::get_policy_version($versionid);
99             if (!api::can_user_view_policy_version($version, $behalfid)) {
100                 $warnings[] = [
101                     'item' => $versionid,
102                     'warningcode' => 'errorusercantviewpolicyversion',
103                     'message' => get_string('errorusercantviewpolicyversion', 'tool_policy')
104                 ];
105             } else if (!empty($version)) {
106                 $version = api::get_policy_version($versionid);
107                 $policy['name'] = $version->name;
108                 $policy['versionid'] = $versionid;
109                 list($policy['content'], $notusedformat) = external_format_text(
110                     $version->content,
111                     $version->contentformat,
112                     SYSCONTEXTID,
113                     'tool_policy',
114                     'policydocumentcontent',
115                     $version->id
116                 );
117                 $result['policy'] = $policy;
118             }
119         } catch (moodle_exception $e) {
120             $warnings[] = [
121                 'item' => $versionid,
122                 'warningcode' => 'errorpolicyversionnotfound',
123                 'message' => get_string('errorpolicyversionnotfound', 'tool_policy')
124             ];
125         }
127         return [
128             'result' => $result,
129             'warnings' => $warnings
130         ];
131     }
133     /**
134      * Parameter description for get_policy_version().
135      *
136      * @return external_description
137      */
138     public static function get_policy_version_returns() {
139         return new external_single_structure([
140             'result' => new external_single_structure([
141                             'policy' => new external_single_structure([
142                                     'name' => new external_value(PARAM_RAW, 'The policy version name', VALUE_OPTIONAL),
143                                     'versionid' => new external_value(PARAM_INT, 'The policy version id', VALUE_OPTIONAL),
144                                     'content' => new external_value(PARAM_RAW, 'The policy version content', VALUE_OPTIONAL)
145                                     ], 'Policy information', VALUE_OPTIONAL)
146                             ]),
147             'warnings' => new external_warnings()
148         ]);
149     }
151     /**
152      * Describes the parameters for submit_create_group_form webservice.
153      * @return external_function_parameters
154      */
155     public static function submit_accept_on_behalf_parameters() {
156         return new external_function_parameters(
157             array(
158                 'jsonformdata' => new external_value(PARAM_RAW, 'The data from the create group form, encoded as a json array')
159             )
160         );
161     }
163     /**
164      * Submit the create group form.
165      *
166      * @param string $jsonformdata The data from the form, encoded as a json array.
167      * @return int new group id.
168      */
169     public static function submit_accept_on_behalf($jsonformdata) {
170         // We always must pass webservice params through validate_parameters.
171         $params = self::validate_parameters(self::submit_accept_on_behalf_parameters(),
172             ['jsonformdata' => $jsonformdata]);
174         self::validate_context(context_system::instance());
176         $serialiseddata = json_decode($params['jsonformdata']);
178         $data = array();
179         parse_str($serialiseddata, $data);
181         // The last param is the ajax submitted data.
182         $mform = new accept_policy(null, $data, 'post', '', null, true, $data);
184         // Do the action.
185         $mform->process();
187         return true;
188     }
190     /**
191      * Returns description of method result value.
192      *
193      * @return external_description
194      * @since Moodle 3.0
195      */
196     public static function submit_accept_on_behalf_returns() {
197         return new external_value(PARAM_BOOL, 'success');
198     }