Merge pull request #124 from Xymph/124-logout

Add method Wikimate::logout()

CHANGELOG.md

@@ -7,6 +7,7 @@ Since v0.10.0 this project adheres to [Semantic Versioning](http://semver.org/)
 #### Added
 
 * New methods `WikiFile::revert()` and `Wikimate::filerevert()` ([#123])
+* New method `Wikimate::logout()` ([#124])
 
 #### Changed
 
@@ -151,3 +152,4 @@ Since v0.10.0 this project adheres to [Semantic Versioning](http://semver.org/)
 [#121]: https://github.com/hamstar/Wikimate/pull/121
 [#122]: https://github.com/hamstar/Wikimate/pull/122
 [#123]: https://github.com/hamstar/Wikimate/pull/123
+[#124]: https://github.com/hamstar/Wikimate/pull/124

USAGE.md

@@ -341,7 +341,7 @@ Both methods return an array of the MediaWiki API result.
 API requests are made over HTTP with a user agent string to identify
 the client to the server. By default the user agent is formatted as:
 
-`Wikimate <VERSION> (https://github.com/hamstar/Wikimate)`
+`Wikimate/<VERSION> (https://github.com/hamstar/Wikimate)`
 
 The string can be retrieved and customized via:
 
@@ -363,7 +363,8 @@ print_r($page->getError());
 ```
 
 For MediaWiki API errors, the array contains the 'code' and 'info' key/value pairs [defined by the API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Errors_and_warnings#Errors).  For other errors, the following key/value pairs are returned:
-* 'login' for Wikimate authentication problems
+* 'login' for Wikimate authentication problems <!-- TODO: remove after changing login() to use the 'auth' code too -->
+* 'auth' for Wikimate authentication problems
 * 'token' for Wikimate token problems
 * 'page' for WikiPage errors
 * 'file' for WikiFile errors

Wikimate.php

@@ -241,6 +241,8 @@ private function request($data, $headers = array(), $post = false)
 	 *
 	 * If a CSRF (default) token is requested, it is stored and returned
 	 * upon further such requests, instead of making another API call.
+	 * The stored token is discarded via {@see Wikimate::logout()}.
+	 *
 	 * For now this method, in Wikimate tradition, is kept simple and supports
 	 * only the two token types needed elsewhere in the library.  It also
 	 * doesn't support the option to request multiple tokens at once.
@@ -374,6 +376,56 @@ public function login($username, $password, $domain = null)
 		return true;
 	}
 
+	/**
+	 * Logs out of the wiki and discard CSRF token.
+	 *
+	 * @return  boolean  True if logged out
+	 * @link https://www.mediawiki.org/wiki/Special:MyLanguage/API:Logout
+	 */
+	public function logout()
+	{
+		// Obtain logout token first
+		if (($logouttoken = $this->token()) === null) {
+			return false;
+		}
+
+		// Token is needed in MediaWiki v1.34+, older versions produce an
+		// 'Unrecognized parameter' warning which can be ignored
+		$details = array(
+			'action' => 'logout',
+			'token' => $logouttoken,
+		);
+
+		// Send the logout request
+		$response = $this->request($details, array(), true);
+
+		// Check if we got an API result or the API doc page (invalid request)
+		if (strpos($response->body, "This is an auto-generated MediaWiki API documentation page") !== false) {
+			$this->error = array();
+			$this->error['auth'] = 'The API could not understand the logout request';
+			return false;
+		}
+
+		$logoutResult = json_decode($response->body, true);
+		// Check if we got a JSON result
+		if ($logoutResult === null) {
+			$this->error = array();
+			$this->error['auth'] = 'The API did not return the logout response';
+			return false;
+		}
+
+		if ($this->debugMode) {
+			echo "Logout request:\n";
+			print_r($details);
+			echo "Logout response:\n";
+			print_r($logoutResult);
+		}
+
+		// Discard CSRF token for this login session
+		$this->csrf_token = null;
+		return true;
+	}
+
 	/**
 	 * Gets the current value of the maxlag parameter.
 	 *