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 Users class for the Joomla Platform.
14 *
15 * @since 12.3
16 */
17 class JMediawikiUsers extends JMediawikiObject
18 {
19 /**
20 * Method to login and get authentication tokens.
21 *
22 * @param string $lgname User Name.
23 * @param string $lgpassword Password.
24 * @param string $lgdomain Domain (optional).
25 *
26 * @return object
27 *
28 * @since 12.3
29 */
30 public function login($lgname, $lgpassword, $lgdomain = null)
31 {
32 // Build the request path.
33 $path = '?action=login&lgname=' . $lgname . '&lgpassword=' . $lgpassword;
34
35 if (isset($lgdomain))
36 {
37 $path .= '&lgdomain=' . $lgdomain;
38 }
39
40 // Send the request.
41 $response = $this->client->post($this->fetchUrl($path), null);
42
43 // Request path with login token.
44 $path = '?action=login&lgname=' . $lgname . '&lgpassword=' . $lgpassword . '&lgtoken=' . $this->validateResponse($response)->login['token'];
45
46 if (isset($lgdomain))
47 {
48 $path .= '&lgdomain=' . $lgdomain;
49 }
50
51 // Set the session cookies returned.
52 $headers = (array) $this->options->get('headers');
53 $headers['Cookie'] = !empty($headers['Cookie']) ? empty($headers['Cookie']) : '';
54 $headers['Cookie'] = $headers['Cookie'] . $response->headers['Set-Cookie'];
55 $this->options->set('headers', $headers);
56
57 // Send the request again with the token.
58 $response = $this->client->post($this->fetchUrl($path), null);
59 $response_body = $this->validateResponse($response);
60
61 $headers = (array) $this->options->get('headers');
62 $cookie_prefix = $response_body->login['cookieprefix'];
63 $cookie = $cookie_prefix . 'UserID=' . $response_body->login['lguserid'] . '; ' . $cookie_prefix
64 . 'UserName=' . $response_body->login['lgusername'];
65 $headers['Cookie'] = $headers['Cookie'] . '; ' . $response->headers['Set-Cookie'] . '; ' . $cookie;
66 $this->options->set('headers', $headers);
67
68 return $this->validateResponse($response);
69 }
70
71 /**
72 * Method to logout and clear session data.
73 *
74 * @return object
75 *
76 * @since 12.3
77 */
78 public function logout()
79 {
80 // Build the request path.
81 $path = '?action=login';
82
83 // @TODO clear internal data as well
84
85 // Send the request.
86 $response = $this->client->get($this->fetchUrl($path));
87
88 return $this->validateResponse($response);
89 }
90
91 /**
92 * Method to get user information.
93 *
94 * @param array $ususers A list of users to obtain the same information for.
95 * @param array $usprop What pieces of information to include.
96 *
97 * @return object
98 *
99 * @since 12.3
100 */
101 public function getUserInfo(array $ususers, array $usprop = null)
102 {
103 // Build the request path.
104 $path = '?action=query&list=users';
105
106 // Append users to the request.
107 $path .= '&ususers=' . $this->buildParameter($ususers);
108
109 if (isset($usprop))
110 {
111 $path .= '&usprop' . $this->buildParameter($usprop);
112 }
113
114 // Send the request.
115 $response = $this->client->get($this->fetchUrl($path));
116
117 return $this->validateResponse($response);
118 }
119
120 /**
121 * Method to get current user information.
122 *
123 * @param array $uiprop What pieces of information to include.
124 *
125 * @return object
126 *
127 * @since 12.3
128 */
129 public function getCurrentUserInfo(array $uiprop = null)
130 {
131 // Build the request path.
132 $path = '?action=query&meta=userinfo';
133
134 if (isset($uiprop))
135 {
136 $path .= '&uiprop' . $this->buildParameter($uiprop);
137 }
138
139 // Send the request.
140 $response = $this->client->get($this->fetchUrl($path));
141
142 return $this->validateResponse($response);
143 }
144
145 /**
146 * Method to get user contributions.
147 *
148 * @param string $ucuser The users to retrieve contributions for.
149 * @param string $ucuserprefix Retrieve contibutions for all users whose names begin with this value.
150 * @param integer $uclimit The users to retrieve contributions for.
151 * @param string $ucstart The start timestamp to return from.
152 * @param string $ucend The end timestamp to return to.
153 * @param boolean $uccontinue When more results are available, use this to continue.
154 * @param string $ucdir In which direction to enumerate.
155 * @param array $ucnamespace Only list contributions in these namespaces.
156 * @param array $ucprop Include additional pieces of information.
157 * @param array $ucshow Show only items that meet this criteria.
158 * @param string $uctag Only list revisions tagged with this tag.
159 * @param string $uctoponly Only list changes which are the latest revision
160 *
161 * @return object
162 *
163 * @since 12.3
164 */
165 public function getUserContribs($ucuser = null, $ucuserprefix = null, $uclimit = null, $ucstart = null, $ucend = null, $uccontinue = null,
166 $ucdir = null, array $ucnamespace = null, array $ucprop = null, array $ucshow = null, $uctag = null, $uctoponly = null)
167 {
168 // Build the request path.
169 $path = '?action=query&list=usercontribs';
170
171 if (isset($ucuser))
172 {
173 $path .= '&ucuser=' . $ucuser;
174 }
175
176 if (isset($ucuserprefix))
177 {
178 $path .= '&ucuserprefix=' . $ucuserprefix;
179 }
180
181 if (isset($uclimit))
182 {
183 $path .= '&uclimit=' . $uclimit;
184 }
185
186 if (isset($ucstart))
187 {
188 $path .= '&ucstart=' . $ucstart;
189 }
190
191 if (isset($ucend))
192 {
193 $path .= '&ucend=' . $ucend;
194 }
195
196 if ($uccontinue)
197 {
198 $path .= '&uccontinue=';
199 }
200
201 if (isset($ucdir))
202 {
203 $path .= '&ucdir=' . $ucdir;
204 }
205
206 if (isset($ucnamespace))
207 {
208 $path .= '&ucnamespace=' . $this->buildParameter($ucnamespace);
209 }
210
211 if (isset($ucprop))
212 {
213 $path .= '&ucprop=' . $this->buildParameter($ucprop);
214 }
215
216 if (isset($ucshow))
217 {
218 $path .= '&ucshow=' . $this->buildParameter($ucshow);
219 }
220
221 if (isset($uctag))
222 {
223 $path .= '&uctag=' . $uctag;
224 }
225
226 if (isset($uctoponly))
227 {
228 $path .= '&uctoponly=' . $uctoponly;
229 }
230
231 // Send the request.
232 $response = $this->client->get($this->fetchUrl($path));
233
234 return $this->validateResponse($response);
235 }
236
237 /**
238 * Method to block a user.
239 *
240 * @param string $user Username, IP address or IP range you want to block.
241 * @param string $expiry Relative expiry time, Default: never.
242 * @param string $reason Reason for block (optional).
243 * @param boolean $anononly Block anonymous users only.
244 * @param boolean $nocreate Prevent account creation.
245 * @param boolean $autoblock Automatically block the last used IP address, and any subsequent IP addresses they try to login from.
246 * @param boolean $noemail Prevent user from sending email through the wiki.
247 * @param boolean $hidename Hide the username from the block log.
248 * @param boolean $allowusertalk Allow the user to edit their own talk page.
249 * @param boolean $reblock If the user is already blocked, overwrite the existing block.
250 * @param boolean $watchuser Watch the user/IP's user and talk pages.
251 *
252 * @return object
253 *
254 * @since 12.3
255 */
256 public function blockUser($user, $expiry = null, $reason = null, $anononly = null, $nocreate = null, $autoblock = null, $noemail = null,
257 $hidename = null, $allowusertalk = null, $reblock = null, $watchuser = null)
258 {
259 // Get the token.
260 $token = $this->getToken($user, 'block');
261
262 // Build the request path.
263 $path = '?action=unblock';
264
265 // Build the request data.
266 $data = array(
267 'user' => $user,
268 'token' => $token,
269 'expiry' => $expiry,
270 'reason' => $reason,
271 'anononly' => $anononly,
272 'nocreate' => $nocreate,
273 'autoblock' => $autoblock,
274 'noemail' => $noemail,
275 'hidename' => $hidename,
276 'allowusetalk' => $allowusertalk,
277 'reblock' => $reblock,
278 'watchuser' => $watchuser,
279 );
280
281 // Send the request.
282 $response = $this->client->post($this->fetchUrl($path), $data);
283
284 return $this->validateResponse($response);
285 }
286
287 /**
288 * Method to unblock a user.
289 *
290 * @param string $user Username, IP address or IP range you want to unblock.
291 * @param string $reason Reason for unblock (optional).
292 *
293 * @return object
294 *
295 * @since 12.3
296 */
297 public function unBlockUserByName($user, $reason = null)
298 {
299 // Get the token.
300 $token = $this->getToken($user, 'unblock');
301
302 // Build the request path.
303 $path = '?action=unblock';
304
305 // Build the request data.
306 $data = array(
307 'user' => $user,
308 'token' => $token,
309 'reason' => $reason,
310 );
311
312 // Send the request.
313 $response = $this->client->post($this->fetchUrl($path), $data);
314
315 return $this->validateResponse($response);
316 }
317
318 /**
319 * Method to unblock a user.
320 *
321 * @param int $id Username, IP address or IP range you want to unblock.
322 * @param string $reason Reason for unblock (optional).
323 *
324 * @return object
325 *
326 * @since 12.3
327 */
328 public function unBlockUserById($id, $reason = null)
329 {
330 // Get the token.
331 $token = $this->getToken($id, 'unblock');
332
333 // Build the request path.
334 $path = '?action=unblock';
335
336 // Build the request data.
337 // TODO: $data doesn't seem to be used!
338 $data = array(
339 'id' => $id,
340 'token' => $token,
341 'reason' => $reason,
342 );
343
344 // Send the request.
345 $response = $this->client->get($this->fetchUrl($path));
346
347 return $this->validateResponse($response);
348 }
349
350 /**
351 * Method to assign a user to a group.
352 *
353 * @param string $username User name.
354 * @param array $add Add the user to these groups.
355 * @param array $remove Remove the user from these groups.
356 * @param string $reason Reason for the change.
357 *
358 * @return object
359 *
360 * @since 12.3
361 */
362 public function assignGroup($username, $add = null, $remove = null, $reason = null)
363 {
364 // Get the token.
365 $token = $this->getToken($username, 'unblock');
366
367 // Build the request path.
368 $path = '?action=userrights';
369
370 // Build the request data.
371 $data = array(
372 'username' => $username,
373 'token' => $token,
374 'add' => $add,
375 'remove' => $remove,
376 'reason' => $reason,
377 );
378
379 // Send the request.
380 $response = $this->client->post($this->fetchUrl($path), $data);
381
382 return $this->validateResponse($response);
383 }
384
385 /**
386 * Method to email a user.
387 *
388 * @param string $target User to send email to.
389 * @param string $subject Subject header.
390 * @param string $text Mail body.
391 * @param boolean $ccme Send a copy of this mail to me.
392 *
393 * @return object
394 *
395 * @since 12.3
396 */
397 public function emailUser($target, $subject = null, $text = null, $ccme = null)
398 {
399 // Get the token.
400 $token = $this->getToken($target, 'emailuser');
401
402 // Build the request path.
403 $path = '?action=emailuser';
404
405 // Build the request data.
406 $data = array(
407 'target' => $target,
408 'token' => $token,
409 'subject' => $subject,
410 'text' => $text,
411 'ccme' => $ccme,
412 );
413
414 // Send the request.
415 $response = $this->client->post($this->fetchUrl($path), $data);
416
417 return $this->validateResponse($response);
418 }
419
420 /**
421 * Method to get access token.
422 *
423 * @param string $user The User to get token.
424 * @param string $intoken The type of token.
425 *
426 * @return object
427 *
428 * @since 12.3
429 */
430 public function getToken($user, $intoken)
431 {
432 // Build the request path.
433 $path = '?action=query&prop=info&intoken=' . $intoken . '&titles=User:' . $user;
434
435 // Send the request.
436 $response = $this->client->post($this->fetchUrl($path), null);
437
438 return (string) $this->validateResponse($response)->query->pages->page[$intoken . 'token'];
439 }
440 }
441