Merge pull request #20 from JeroenDeDauw/seggregate

Add interfaces

RELEASENOTES.md

@@ -1,18 +1,27 @@
 These are the release notes for the [mediawiki-api-base](README.md).
 
+## Version 2.2.0 (dev)
+
+* Added `MediawikiApiInterface`, now implemented by `MediawikiApi`
+* Added `ApiRequester`, now implemented by `MediawikiApi`
+* Added `AsyncApiRequester`, now implemented by `MediawikiApi`
+
 ## Version 2.1.0 (29 December 2015)
+
 * Retry throttled actions that return a failed-save code and anti-abuse message
 * Added delay between retried requests
 * Added and used `Guzzle/ClientFactory`
 
 ## Version 2.0.0 (18 December 2015)
+
 * Added `MediawikiApi::newFromApiEndpoint` and `MediawikiApi::newFromPage`
 * MediawikiApi constructor access marked as private (please use static factory methods)
 * Added async methods to MediawikiApi `getRequestAsync` & `postRequestAsync`
 * Requires "guzzlehttp/guzzle": "~6.0" ( From "guzzle/guzzle": "~5.2" )
 * Requires "guzzlehttp/promises": "~1.0"
 
 ## Version 1.1.0 (5 September 2015)
+
 * Requests that encounter a connection exception are now retried
 * Requests that result in non blocking mediawiki api error codes are now retried (ratelimited, readonly, internal_api_error_DBQueryError)
 * MediawikiApi now implements PSR-3 LoggerAwareInterface

src/ApiRequester.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Mediawiki\Api;
+
+/**
+ * @since 2.2
+ * @licence GNU GPL v2+
+ * @author Addshore
+ * @author Jeroen De Dauw < [email protected] >
+ */
+interface ApiRequester {
+
+	/**
+	 * @since 2.2
+	 *
+	 * @param Request $request
+	 *
+	 * @return mixed Normally an array
+	 */
+	public function getRequest( Request $request );
+
+	/**
+	 * @since 2.2
+	 *
+	 * @param Request $request
+	 *
+	 * @return mixed Normally an array
+	 */
+	public function postRequest( Request $request );
+
+}

src/AsyncApiRequester.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Mediawiki\Api;
+
+use GuzzleHttp\Promise\PromiseInterface;
+
+/**
+ * @since 2.2
+ * @licence GNU GPL v2+
+ * @author Addshore
+ * @author Jeroen De Dauw < [email protected] >
+ */
+interface AsyncApiRequester {
+
+	/**
+	 * @since 2.2
+	 *
+	 * @param Request $request
+	 *
+	 * @return PromiseInterface
+	 *         Normally promising an array, though can be mixed (json_decode result)
+	 *         Can throw UsageExceptions or RejectionExceptions
+	 */
+	public function getRequestAsync( Request $request );
+
+	/**
+	 * @since 2.2
+	 *
+	 * @param Request $request
+	 *
+	 * @return PromiseInterface
+	 *         Normally promising an array, though can be mixed (json_decode result)
+	 *         Can throw UsageExceptions or RejectionExceptions
+	 */
+	public function postRequestAsync( Request $request );
+
+}

src/MediawikiApi.php

@@ -25,7 +25,7 @@
  *
  * @author Addshore
  */
-class MediawikiApi implements LoggerAwareInterface {
+class MediawikiApi implements MediawikiApiInterface, LoggerAwareInterface {
 
 	/**
 	 * @var Client|null Should be accessed through getClient

src/MediawikiApiInterface.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Mediawiki\Api;
+
+/**
+ * @since 2.2
+ * @licence GNU GPL v2+
+ * @author Addshore
+ * @author Jeroen De Dauw < [email protected] >
+ */
+interface MediawikiApiInterface extends ApiRequester, AsyncApiRequester {
+
+	/**
+	 * @since 2.2
+	 *
+	 * @return bool|string false or the name of the current user
+	 */
+	public function isLoggedin();
+
+	/**
+	 * @since 2.2
+	 *
+	 * @param ApiUser $apiUser
+	 *
+	 * @throws UsageException
+	 * @return bool success
+	 */
+	public function login( ApiUser $apiUser );
+
+	/**
+	 * @since 2.2
+	 *
+	 * @return bool success
+	 */
+	public function logout();
+
+	/**
+	 * @since 2.2
+	 *
+	 * @param string $type
+	 *
+	 * @return string
+	 */
+	public function getToken( $type = 'csrf' );
+
+	/**
+	 * @since 2.2
+	 *
+	 * Clears all tokens stored by the api
+	 */
+	public function clearTokens();
+
+	/**
+	 * @since 2.2
+	 *
+	 * @return string
+	 */
+	public function getVersion();
+
+}