MDL-63805 glossary: New WS mod_glossary_update_entry
[moodle.git] / mod / glossary / classes / external / update_entry.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 method for updating a glossary entry.
19  *
20  * @package    mod_glossary
21  * @since      Moodle 3.10
22  * @copyright  2020 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 namespace mod_glossary\external;
28 defined('MOODLE_INTERNAL') || die();
30 global $CFG;
31 require_once($CFG->libdir . '/externallib.php');
32 require_once($CFG->dirroot . '/mod/glossary/lib.php');
34 use external_api;
35 use external_function_parameters;
36 use external_multiple_structure;
37 use external_single_structure;
38 use external_value;
39 use external_format_value;
40 use external_warnings;
41 use core_text;
42 use moodle_exception;
44 /**
45  * This is the external method for updating a glossary entry.
46  *
47  * @copyright  2020 Juan Leyva <juan@moodle.com>
48  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
49  */
50 class update_entry extends external_api {
51     /**
52      * Parameters.
53      *
54      * @return external_function_parameters
55      */
56     public static function execute_parameters(): external_function_parameters {
57         return new external_function_parameters([
58             'entryid' => new external_value(PARAM_INT, 'Glossary entry id to update'),
59             'concept' => new external_value(PARAM_TEXT, 'Glossary concept'),
60             'definition' => new external_value(PARAM_RAW, 'Glossary concept definition'),
61             'definitionformat' => new external_format_value('definition'),
62             'options' => new external_multiple_structure (
63                 new external_single_structure(
64                     [
65                         'name' => new external_value(PARAM_ALPHANUM,
66                             'The allowed keys (value format) are:
67                             inlineattachmentsid (int); the draft file area id for inline attachments
68                             attachmentsid (int); the draft file area id for attachments
69                             categories (comma separated int); comma separated category ids
70                             aliases (comma separated str); comma separated aliases
71                             usedynalink (bool); whether the entry should be automatically linked.
72                             casesensitive (bool); whether the entry is case sensitive.
73                             fullmatch (bool); whether to match whole words only.'),
74                         'value' => new external_value(PARAM_RAW, 'the value of the option (validated inside the function)')
75                     ]
76                 ), 'Optional settings', VALUE_DEFAULT, []
77             )
78         ]);
79     }
81     /**
82      * Update the indicated glossary entry.
83      *
84      * @param  int $entryid The entry to update
85      * @param string $concept    the glossary concept
86      * @param string $definition the concept definition
87      * @param int $definitionformat the concept definition format
88      * @param array  $options    additional settings
89      * @return array with result and warnings
90      * @throws moodle_exception
91      */
92     public static function execute(int $entryid, string $concept, string $definition, int $definitionformat,
93             array $options = []): array {
95         global $DB;
97         $params = self::validate_parameters(self::execute_parameters(), compact('entryid', 'concept', 'definition',
98             'definitionformat', 'options'));
99         $id = $params['entryid'];
101         // Get and validate the glossary entry.
102         $entry = $DB->get_record('glossary_entries', ['id' => $id], '*', MUST_EXIST);
103         list($glossary, $context, $course, $cm) = \mod_glossary_external::validate_glossary($entry->glossaryid);
105         // Check if the user can update the entry.
106         mod_glossary_can_update_entry($entry, $glossary, $context, $cm, false);
108         // Check for duplicates if the concept changes.
109         if (!$glossary->allowduplicatedentries &&
110                 core_text::strtolower($entry->concept) != core_text::strtolower(trim($params['concept']))) {
112             if (glossary_concept_exists($glossary, $params['concept'])) {
113                 throw new moodle_exception('errconceptalreadyexists', 'glossary');
114             }
115         }
117         // Prepare the entry object.
118         $entry->aliases = '';
119         $entry = mod_glossary_prepare_entry_for_edition($entry);
120         $entry->concept = $params['concept'];
121         $entry->definition_editor = [
122             'text' => $params['definition'],
123             'format' => $params['definitionformat'],
124         ];
125         // Options.
126         foreach ($params['options'] as $option) {
127             $name = trim($option['name']);
128             switch ($name) {
129                 case 'inlineattachmentsid':
130                     $entry->definition_editor['itemid'] = clean_param($option['value'], PARAM_INT);
131                     break;
132                 case 'attachmentsid':
133                     $entry->attachment_filemanager = clean_param($option['value'], PARAM_INT);
134                     break;
135                 case 'categories':
136                     $entry->categories = clean_param($option['value'], PARAM_SEQUENCE);
137                     $entry->categories = explode(',', $entry->categories);
138                     break;
139                 case 'aliases':
140                     $entry->aliases = clean_param($option['value'], PARAM_NOTAGS);
141                     // Convert to the expected format.
142                     $entry->aliases = str_replace(",", "\n", $entry->aliases);
143                     break;
144                 case 'usedynalink':
145                 case 'casesensitive':
146                 case 'fullmatch':
147                     // Only allow if linking is enabled.
148                     if ($glossary->usedynalink) {
149                         $entry->{$name} = clean_param($option['value'], PARAM_BOOL);
150                     }
151                     break;
152                 default:
153                     throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
154             }
155         }
157         $entry = glossary_edit_entry($entry, $course, $cm, $glossary, $context);
159         return [
160             'result' => true,
161             'warnings' => [],
162         ];
163     }
165     /**
166      * Return.
167      *
168      * @return external_single_structure
169      */
170     public static function execute_returns(): external_single_structure {
171         return new external_single_structure([
172             'result' => new external_value(PARAM_BOOL, 'The update result'),
173             'warnings' => new external_warnings()
174         ]);
175     }