MDL-35997 Create web service functions to return lang strings
[moodle.git] / lib / external / externallib.php
CommitLineData
11e76602
JM
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/**
19 * external API for core library
20 *
21 * @package core_webservice
22 * @category external
23 * @copyright 2012 Jerome Mouneyrac <jerome@moodle.com>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once("$CFG->libdir/externallib.php");
30
31/**
32 * Web service related functions
33 *
34 * @package core
35 * @category external
36 * @copyright 2012 Jerome Mouneyrac <jerome@moodle.com>
37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 * @since Moodle 2.4
39 */
40class core_external extends external_api {
41
42
43 /**
44 * Format the received string parameters to be sent to the core get_string() function.
45 *
46 * @param array $stringparams
47 * @return object|string
48 * @since 2.4
49 */
50 public static function format_string_parameters($stringparams) {
51 // Check if there are some string params.
52 $strparams = new stdClass();
53 if (!empty($stringparams)) {
54 // There is only one string parameter.
55 if (count($stringparams) == 1) {
56 $stringparam = array_pop($stringparams);
57 if (isset($stringparam['name'])) {
58 $strparams->{$stringparam['name']} = $stringparam['value'];
59 } else {
60 // It is a not named string parameter.
61 $strparams = $stringparam['value'];
62 }
63 } else {
64 // There are more than one parameter.
65 foreach ($stringparams as $stringparam) {
66
67 // If a parameter is unnamed throw an exception
68 // unnamed param is only possible if one only param is sent.
69 if (empty($stringparam['name'])) {
70 throw new moodle_exception('unamedstringparam', 'webservice');
71 }
72
73 $strparams->{$stringparam['name']} = $stringparam['value'];
74 }
75 }
76 }
77 return $strparams;
78 }
79
80 /**
81 * Returns description of get_string parameters
82 *
83 * @return external_function_parameters
84 * @since Moodle 2.4
85 */
86 public static function get_string_parameters() {
87 return new external_function_parameters(
88 array('stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
89 'component' => new external_value(PARAM_COMPONENT,'component', VALUE_DEFAULT, 'moodle'),
90 'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
91 'stringparams' => new external_multiple_structure (
92 new external_single_structure(array(
93 'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
94 - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
95 'value' => new external_value(PARAM_TEXT,'param value'))),
96 'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
97 )
98 )
99 );
100 }
101
102 /**
103 * Return a core get_string() call
104 *
105 * @param string $identifier string identifier
106 * @param string $component string component
107 * @param array $stringparams the string params
108 * @return string
109 * @since Moodle 2.4
110 */
111 public static function get_string($stringid, $component = 'moodle', $stringparams = array()) {
112 $params = self::validate_parameters(self::get_string_parameters(),
113 array('stringid'=>$stringid, 'component' => $component, 'stringparams' => $stringparams));
114
115 return get_string($params['stringid'], $params['component'],
116 core_external::format_string_parameters($params['stringparams']), $params['lang']);
117 }
118
119 /**
120 * Returns description of get_string() result value
121 *
122 * @return string
123 * @since Moodle 2.4
124 */
125 public static function get_string_returns() {
126 return new external_value(PARAM_TEXT, 'translated string');
127 }
128
129 /**
130 * Returns description of get_string parameters
131 *
132 * @return external_function_parameters
133 * @since Moodle 2.4
134 */
135 public static function get_strings_parameters() {
136 return new external_function_parameters(
137 array('strings' => new external_multiple_structure (
138 new external_single_structure (array(
139 'stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
140 'component' => new external_value(PARAM_COMPONENT, 'component', VALUE_DEFAULT, 'moodle'),
141 'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
142 'stringparams' => new external_multiple_structure (
143 new external_single_structure(array(
144 'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
145 - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
146 'value' => new external_value(PARAM_TEXT, 'param value'))),
147 'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
148 ))
149 )
150 )
151 )
152 );
153 }
154
155 /**
156 * Return multiple call to core get_string()
157 *
158 * @param array $strings strings to translate
159 * @return array
160 *
161 * @since Moodle 2.4
162 */
163 public static function get_strings($strings) {
164 $params = self::validate_parameters(self::get_strings_parameters(),
165 array('strings'=>$strings));
166
167 $translatedstrings = array();
168 foreach($params['strings'] as $string) {
169
170 if (empty($string['lang'])) {
171 $lang = $string['lang'];
172 } else {
173 $lang = current_language();
174 }
175
176 $translatedstrings[] = array(
177 'stringid' => $string['stringid'],
178 'component' => $string['component'],
179 'lang' => $lang,
180 'string' => get_string($string['stringid'], $string['component'],
181 core_external::format_string_parameters($string['stringparams']), $lang));
182 }
183
184 return $translatedstrings;
185 }
186
187 /**
188 * Returns description of get_string() result value
189 *
190 * @return array
191 * @since Moodle 2.4
192 */
193 public static function get_strings_returns() {
194 return new external_multiple_structure(
195 new external_single_structure(array(
196 'stringid' => new external_value(PARAM_STRINGID, 'string id'),
197 'component' => new external_value(PARAM_COMPONENT, 'string component'),
198 'lang' => new external_value(PARAM_LANG, 'lang'),
199 'string' => new external_value(PARAM_TEXT, 'translated string'))
200 ));
201 }
202
203 /**
204 * Returns description of get_component_strings parameters
205 *
206 * @return external_function_parameters
207 * @since Moodle 2.4
208 */
209 public static function get_component_strings_parameters() {
210 return new external_function_parameters(
211 array('component' => new external_value(PARAM_COMPONENT, 'component'),
212 'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
213 )
214 );
215 }
216
217 /**
218 * Return all lang strings of a component - call to core get_component_strings().
219 *
220 * @param string $component component name
221 * @return array
222 *
223 * @since Moodle 2.4
224 */
225 public static function get_component_strings($component, $lang = null) {
226
227 if (empty($lang)) {
228 $lang = current_language();
229 }
230
231 $params = self::validate_parameters(self::get_component_strings_parameters(),
232 array('component'=>$component, 'lang' => $lang));
233
234 $stringmanager = get_string_manager();
235
236 $wsstrings = array();
237 $componentstrings = $stringmanager->load_component_strings($params['component'], $params['lang']);
238 foreach($componentstrings as $stringid => $string) {
239 $wsstrings[$stringid] = $string;
240 }
241
242 return $wsstrings;
243 }
244
245 /**
246 * Returns description of get_component_strings() result value
247 *
248 * @return array
249 * @since Moodle 2.4
250 */
251 public static function get_component_strings_returns() {
252 return new external_multiple_structure(
253 new external_single_structure(array(
254 'stringid' => new external_value(PARAM_STRINGID, 'string id'),
255 'string' => new external_value(PARAM_TEXT, 'translated string'))
256 ));
257 }
258}