1 <?php
2 /**
3 * @package Joomla.Platform
4 * @subpackage MediaWiki
5 *
6 * @copyright Copyright (C) 2005 - 2017 Open Source Matters, Inc. All rights reserved.
7 * @license GNU General Public License version 2 or later; see LICENSE
8 */
9
10 defined('JPATH_PLATFORM') or die;
11
12 /**
13 * MediaWiki API Categories class for the Joomla Platform.
14 *
15 * @since 12.3
16 */
17 class JMediawikiCategories extends JMediawikiObject
18 {
19 /**
20 * Method to list all categories the page(s) belong to.
21 *
22 * @param array $titles Page titles to retrieve categories.
23 * @param array $clprop List of additional properties to get.
24 * @param array $clshow Type of categories to show.
25 * @param integer $cllimit Number of categories to return.
26 * @param boolean $clcontinue Continue when more results are available.
27 * @param array $clcategories Only list these categories.
28 * @param string $cldir Direction of listing.
29 *
30 * @return object
31 *
32 * @since 12.1
33 */
34 public function getCategories(array $titles, array $clprop = null, array $clshow = null, $cllimit = null, $clcontinue = false,
35 array $clcategories = null, $cldir = null)
36 {
37 // Build the request.
38 $path = '?action=query&prop=categories';
39
40 // Append titles to the request.
41 $path .= '&titles=' . $this->buildParameter($titles);
42
43 if (isset($clprop))
44 {
45 $path .= '&clprop=' . $this->buildParameter($clprop);
46 }
47
48 if (isset($clshow))
49 {
50 $path .= '&$clshow=' . $this->buildParameter($clshow);
51 }
52
53 if (isset($cllimit))
54 {
55 $path .= '&cllimit=' . $cllimit;
56 }
57
58 if ($clcontinue)
59 {
60 $path .= '&clcontinue=';
61 }
62
63 if (isset($clcategories))
64 {
65 $path .= '&clcategories=' . $this->buildParameter($clcategories);
66 }
67
68 if (isset($cldir))
69 {
70 $path .= '&cldir=' . $cldir;
71 }
72
73 // Send the request.
74 $response = $this->client->get($this->fetchUrl($path));
75
76 return $this->validateResponse($response);
77 }
78
79 /**
80 * Method to get information about all categories used.
81 *
82 * @param array $titles Page titles to retrieve categories.
83 *
84 * @return object
85 *
86 * @since 12.3
87 */
88 public function getCategoriesUsed(array $titles)
89 {
90 // Build the request
91 $path = '?action=query&generator=categories&prop=info';
92
93 // Append titles to the request
94 $path .= '&titles=' . $this->buildParameter($titles);
95
96 // Send the request.
97 $response = $this->client->get($this->fetchUrl($path));
98
99 return $this->validateResponse($response);
100 }
101
102 /**
103 * Method to get information about the given categories.
104 *
105 * @param array $titles Page titles to retrieve categories.
106 * @param boolean $clcontinue Continue when more results are available.
107 *
108 * @return object
109 *
110 * @since 12.3
111 */
112 public function getCategoriesInfo(array $titles, $clcontinue = false)
113 {
114 // Build the request.
115 $path = '?action=query&prop=categoryinfo';
116
117 // Append titles to the request
118 $path .= '&titles=' . $this->buildParameter($titles);
119
120 if ($clcontinue)
121 {
122 $path .= '&clcontinue=';
123 }
124
125 // Send the request.
126 $response = $this->client->get($this->fetchUrl($path));
127
128 return $this->validateResponse($response);
129 }
130
131 /**
132 * Method to get information about the pages within a category
133 *
134 * @param string $cmtitle The category title, must contain 'Category:' prefix, cannot be used together with $cmpageid
135 * @param string $cmpageid The category's page ID, cannot be used together with $cmtitle
136 * @param string $cmlimit Maximum number of pages to retrieve
137 * @param array $cmprop Array of properties to retrieve
138 * @param array $cmnamespace Namespaces to retrieve pages from
139 * @param array $cmtype Array of category members to include, ignored if $cmsort is set to 'timestamp'
140 * @param string $cmstart Timestamp to start listing from, only used if $cmsort is set to 'timestamp'
141 * @param string $cmend Timestamp to end listing at, only used if $cmsort is set to 'timestamp'
142 * @param string $cmstartsortkey Hexadecimal key to start listing from, only used if $cmsort is set to 'sortkey'
143 * @param string $cmendsortkey Hexadecimal key to end listing at, only used if $cmsort is set to 'sortkey'
144 * @param string $cmstartsortkeyprefix Hexadecimal key prefix to start listing from, only used if $cmsort is set to 'sortkey',
145 * overrides $cmstartsortkey
146 * @param string $cmendsortkeyprefix Hexadecimal key prefix to end listing before, only used if $cmsort is set to 'sortkey',
147 * overrides $cmendsortkey
148 * @param string $cmsort Property to sort by
149 * @param string $cmdir Direction to sort in
150 * @param string $cmcontinue Used to continue a previous request
151 *
152 * @return object
153 *
154 * @since 3.2.2 (CMS)
155 * @throws RuntimeException
156 */
157 public function getCategoryMembers($cmtitle = null, $cmpageid = null, $cmlimit = null, array $cmprop = null, array $cmnamespace = null,
158 array $cmtype = null, $cmstart = null, $cmend = null, $cmstartsortkey = null, $cmendsortkey = null, $cmstartsortkeyprefix = null,
159 $cmendsortkeyprefix = null, $cmsort = null, $cmdir = null, $cmcontinue = null)
160 {
161 // Build the request.
162 $path = '?action=query&list=categorymembers';
163
164 // Make sure both $cmtitle and $cmpageid are not set
165 if (isset($cmtitle) && isset($cmpageid))
166 {
167 throw new RuntimeException('Both the $cmtitle and $cmpageid parameters cannot be set, please only use one of the two.');
168 }
169
170 if (isset($cmtitle))
171 {
172 // Verify that the Category: prefix exists
173 if (strpos($cmtitle, 'Category:') !== 0)
174 {
175 throw new RuntimeException('The $cmtitle parameter must include the Category: prefix.');
176 }
177
178 $path .= '&cmtitle=' . $cmtitle;
179 }
180
181 if (isset($cmpageid))
182 {
183 $path .= '&cmpageid=' . $cmpageid;
184 }
185
186 if (isset($cmlimit))
187 {
188 $path .= '&cmlimit=' . $cmlimit;
189 }
190
191 if (isset($cmprop))
192 {
193 $path .= '&cmprop=' . $this->buildParameter($cmprop);
194 }
195
196 if (isset($cmnamespace))
197 {
198 $path .= '&cmnamespace=' . $this->buildParameter($cmnamespace);
199 }
200
201 if (isset($cmtype))
202 {
203 $path .= '&cmtype=' . $this->buildParameter($cmtype);
204 }
205
206 if (isset($cmstart))
207 {
208 $path .= '&cmstart=' . $cmstart;
209 }
210
211 if (isset($cmend))
212 {
213 $path .= '&cmend=' . $cmend;
214 }
215
216 if (isset($cmstartsortkey))
217 {
218 $path .= '&cmstartsortkey=' . $cmstartsortkey;
219 }
220
221 if (isset($cmendsortkey))
222 {
223 $path .= '&cmendsortkey=' . $cmendsortkey;
224 }
225
226 if (isset($cmstartsortkeyprefix))
227 {
228 $path .= '&cmstartsortkeyprefix=' . $cmstartsortkeyprefix;
229 }
230
231 if (isset($cmendsortkeyprefix))
232 {
233 $path .= '&cmendsortkeyprefix=' . $cmendsortkeyprefix;
234 }
235
236 if (isset($cmsort))
237 {
238 $path .= '&cmsort=' . $cmsort;
239 }
240
241 if (isset($cmdir))
242 {
243 $path .= '&cmdir=' . $cmdir;
244 }
245
246 if (isset($cmcontinue))
247 {
248 $path .= '&cmcontinue=' . $cmcontinue;
249 }
250
251 // Send the request.
252 $response = $this->client->get($this->fetchUrl($path));
253
254 return $this->validateResponse($response);
255 }
256
257 /**
258 * Method to enumerate all categories.
259 *
260 * @param string $acfrom The category to start enumerating from.
261 * @param string $acto The category to stop enumerating at.
262 * @param string $acprefix Search for all category titles that begin with this value.
263 * @param string $acdir Direction to sort in.
264 * @param integer $acmin Minimum number of category members.
265 * @param integer $acmax Maximum number of category members.
266 * @param integer $aclimit How many categories to return.
267 * @param array $acprop Which properties to get.
268 *
269 * @return object
270 *
271 * @since 12.3
272 */
273 public function enumerateCategories($acfrom = null, $acto = null, $acprefix = null, $acdir = null, $acmin = null,
274 $acmax = null, $aclimit = null, array $acprop = null)
275 {
276 // Build the request.
277 $path = '?action=query&list=allcategories';
278
279 if (isset($acfrom))
280 {
281 $path .= '&acfrom=' . $acfrom;
282 }
283
284 if (isset($acto))
285 {
286 $path .= '&acto=' . $acto;
287 }
288
289 if (isset($acprefix))
290 {
291 $path .= '&acprefix=' . $acprefix;
292 }
293
294 if (isset($acdir))
295 {
296 $path .= '&acdir=' . $acdir;
297 }
298
299 if (isset($acfrom))
300 {
301 $path .= '&acfrom=' . $acfrom;
302 }
303
304 if (isset($acmin))
305 {
306 $path .= '&acmin=' . $acmin;
307 }
308
309 if (isset($acmax))
310 {
311 $path .= '&acmax=' . $acmax;
312 }
313
314 if (isset($aclimit))
315 {
316 $path .= '&aclimit=' . $aclimit;
317 }
318
319 if (isset($acprop))
320 {
321 $path .= '&acprop=' . $this->buildParameter($acprop);
322 }
323
324 // Send the request.
325 $response = $this->client->get($this->fetchUrl($path));
326
327 return $this->validateResponse($response);
328 }
329
330 /**
331 * Method to list change tags.
332 *
333 * @param array $tgprop List of properties to get.
334 * @param string $tglimit The maximum number of tags to limit.
335 *
336 * @return object
337 *
338 * @since 12.3
339 */
340 public function getChangeTags(array $tgprop = null, $tglimit = null)
341 {
342 // Build the request.
343 $path = '?action=query&list=tags';
344
345 if (isset($tgprop))
346 {
347 $path .= '&tgprop=' . $this->buildParameter($tgprop);
348 }
349
350 if (isset($tglimit))
351 {
352 $path .= '&tglimit=' . $tglimit;
353 }
354
355 // @TODO add support for $tgcontinue
356
357 // Send the request.
358 $response = $this->client->get($this->fetchUrl($path));
359
360 return $this->validateResponse($response);
361 }
362 }
363