Merge pull request #25 from hamstar/22-curl2requests

Use Requests library instead of Curl

.gitignore

@@ -1 +1,3 @@
 wikimate_cookie.txt
+nbproject/private
+vendor

README.md

@@ -6,32 +6,22 @@ It consists of two classes currently:
 
 ## Installation
 
-* **Note:** *The commands below apply to Ubuntu. You might need to adjust them for other systems.*
+**Requirements: [PHP](http://php.net), and [Composer](http://getcomposer.org).**
 
 Before anything else, since Wikimate is written in PHP, a server-side language,
-you will need a web server such as Apache to run it (and of course, PHP).
+you will need to have PHP installed to run it. Install it with your preferred
+package management tool (for example, on Ubuntu Linux you can run:
+`sudo apt-get install php5`)
 
-    sudo apt-get install apache2 php5
+Install Composer by following the instructions at https://getcomposer.org/doc/00-intro.md
 
-You will also need cURL; Install it if you don't have it yet.
+Then, download Wikimate, and initialise it by running `composer install` (or
+`composer.bat install` if you're on Windows).
 
-    sudo apt-get install curl php5-curl
-
-Then, download Wikimate.
-To make sure the [curl wrapper submodule](http://github.com/shuber/curl)
-is also downloaded, use git's `--recursive` option:
-
-    git clone --recursive [email protected]:hamstar/Wikimate.git
-
-Now you need to allow the server to write to the cookie file.
-Create a `wikimate_cookie.txt` file in the same directory as the wikimate files
-and give the server write access to that.
-If you don't do this you won't be able to login, and Wikimate will throw an exception.
-
-    cd Wikimate
-    touch wikimate_cookie.txt
-    sudo chown www-data wikimate_cookie.txt
+To use Wikimate within another project, you can add it as a composer dependency
+by adding the following to your `composer.json` file:
 
+    "hamstar/Wikimate": "0.10.0"
 
 ## Usage
 
@@ -232,6 +222,10 @@ Both methods return an array of the MediaWiki API result.
 
 ## Changelog
 
+### Version 0.10.0
+
+* Switched to using the *Requests* library instead of Curl
+
 ### Version 0.5
 
 * Removed the use of constants in favour of constructor arguments

Wikimate.php

@@ -1,53 +1,54 @@
 <?php
 /**
- * Provides an interface over wiki api objects such as pages
- * Logs into the wiki on construction
+ * Provides an interface over wiki API objects such as pages.
  *
  * @author Robert McLeod
  * @since December 2010
- * @version 0.9
+ * @version 0.10.0
  */
-
 class Wikimate {
 
 	const SECTIONLIST_BY_NAME = 1;
 	const SECTIONLIST_BY_INDEX = 2;
-
+
+	/**
+	 * @var string The current version number (conforms to http://semver.org/).
+	 */
+	const VERSION = '0.10.0';
+
 	private $api;
 	private $username;
 	private $password;
-
-	private $c = null;
+
+	/** @var Requests_Session */
+	private $session;
+
 	private $error = array();
 	private $debugMode = false;
 
 	/**
-	 * Creates a curl object and logs in
-	 * If it can't login the class will exit and return null
+	 * Create a new Wikimate object.
+	 * 
+	 * @return Wikimate
 	 */
 	function __construct( $api ) {
 		$this->api = $api;
 
-		$this->initCurl();
-		$this->checkCookieFileIsWritable();
-	}
-
-	private function initCurl() {
-		if ( !class_exists( 'Curl' ) || !class_exists( 'CurlResponse' ) )
-			throw new Exception( "Failed to create Wikimate - could not find the Curl class" );
-
-		$this->c              = new Curl();
-		$this->c->user_agent  = "Wikimate 0.5 (https://github.com/hamstar/Wikimate)";
-		$this->c->cookie_file = "wikimate_cookie.txt";
+		$this->initRequests();
 	}
-
-	private function checkCookieFileIsWritable() {
-		if ( ( !file_exists( $this->c->cookie_file ) && !is_writable( "." ) ) ||
-         (  file_exists( $this->c->cookie_file ) && !is_writable( $this->c->cookie_file ) ) )
-		  throw new Exception( "The cookie file is not writable. Please check that the web server can write to " .
-                           getcwd() . DIRECTORY_SEPARATOR . $this->c->cookie_file );
+
+	/**
+	 * Set up a Requests_Session with appropriate user agent.
+	 *
+	 * @todo Pull version number from elsewhere.
+	 *
+	 * @return void
+	 */
+	private function initRequests() {
+		$this->session = new Requests_Session($this->api);
+		$this->useragent  = "Wikimate ".self::VERSION." (https://github.com/hamstar/Wikimate)";
 	}
-	
+
 	/**
 	 * Logs in to the wiki
 	 * @return boolean true if logged in
@@ -63,15 +64,14 @@ public function login( $username, $password ) {
 		);
 
 		// Send the login request
-		$loginResult = $this->c->post( $this->api, $details )->body;
-
+		$response = $this->session->post($this->api, array(), $details);
 		// Check if we got an API result or the API doc page (invalid request)
-		if ( strstr( $loginResult, "This is an auto-generated MediaWiki API documentation page" ) ) {
+		if ( strstr( $response->body, "This is an auto-generated MediaWiki API documentation page" ) ) {
 			$this->error['login'] = "The API could not understand the first login request";
 			return false;
 		}
-		
-		$loginResult = json_decode( $loginResult );
+
+		$loginResult = json_decode( $response->body );
 
 		if ( $this->debugMode ) {
 			echo "Login request:\n";
@@ -83,9 +83,9 @@ public function login( $username, $password ) {
 		if ( $loginResult->login->result == "NeedToken" ) {
 			//Logger::log("Sending token {$loginResult->login->token}");
 			$details['lgtoken'] = strtolower( trim( $loginResult->login->token ) );
-			
+
 			// Send the confirm token request
-			$loginResult = $this->c->post( $this->api, $details )->body;
+			$loginResult = $this->session->post($this->api, array(), $details)->body;
 
 			// Check if we got an API result or the API doc page (invalid request)
 			if ( strstr( $loginResult, "This is an auto-generated MediaWiki API documentation page" ) ) {
@@ -131,23 +131,41 @@ public function setDebugMode( $b ) {
 		$this->debugMode = $b;
 		return $this;
 	}
-	
+
 	/**
-	 * Either return or print the curl settings.
+	 * Used to return or print the curl settings, but now prints an error and
+	 * returns Wikimate::getRequestsConfig()
 	 *
+	 * @deprecated since version 0.10.0
 	 * @param boolean $echo True to echo the configuration
 	 * @return mixed Array of config if $echo is false, (boolean)true if echo is true
 	 */
 	public function debugCurlConfig( $echo = false ) {
 		if ( $echo ) {
-			echo "Curl Configuration:\n";
-			echo "<pre>", print_r( $this->c->options, 1 ), "</pre>";
+			echo "ERROR: Curl is no longer used by Wikimate.\n";
+		}
+		return $this->getRequestsConfig();
+	}
+
+	/**
+	 * Get or print the Requests configuration.
+	 *
+	 * @param boolean $echo Whether to echo the options
+	 * @return array Options if $echo is FALSE
+	 * @return TRUE If options have been echoed to STDOUT
+	 */
+	public function debugRequestsConfig($echo = FALSE) {
+		if ( $echo ) {
+			echo "<pre>Requests options:\n";
+			print_r($this->session->options);
+			echo "Requests headers:\n";
+			print_r($this->session->headers);
+			echo "</pre>";
 			return true;
 		}
-
-		return $this->c->options;
+		return $this->session->options;
 	}
-	
+
 	/**
 	 * Returns a WikiPage object populated with the page data
 	 * @param string $title The name of the wiki article
@@ -166,12 +184,10 @@ public function query( $array ) {
 		$array['action'] = 'query';
 		$array['format'] = 'php';
 
-		$apiResult = $this->c->get( $this->api, $array );
-
-		return unserialize( $apiResult );
-
+		$apiResult = $this->session->get( $this->api.'?'.http_build_query($array) );
+		return unserialize( $apiResult->body );
 	}
-	
+
 	/**
 	 * Performs a parse query to the wiki API.
 	 * @param array $array array of details to be passed in the query.
@@ -181,9 +197,9 @@ public function parse( $array ) {
 		$array['action'] = 'parse';
 		$array['format'] = 'php';
 
-		$apiResult = $this->c->get( $this->api, $array );
+		$apiResult = $this->session->get( $this->api.'?'.http_build_query($array));
 
-		return unserialize( $apiResult );
+		return unserialize( $apiResult->body );
 	}
 
 	/**
@@ -192,15 +208,16 @@ public function parse( $array ) {
 	 * @return array unserialized php output from the wiki
 	 */
 	public function edit( $array ) {
-		$c                          = $this->c;
-		$c->headers['Content-Type'] = "application/x-www-form-urlencoded";
+		$headers = array(
+			'Content-Type' => "application/x-www-form-urlencoded"
+		);
 
 		$array['action'] = 'edit';
 		$array['format'] = 'php';
 
-		$apiResult = $c->post( $this->api, $array );
+		$apiResult = $this->session->post( $this->api, $headers, $array );
 
-		return unserialize( $apiResult );
+		return unserialize( $apiResult->body );
 	}
 
 	/**
@@ -209,13 +226,14 @@ public function edit( $array ) {
 	 * @return array unserialized php output from the wiki
 	 */
 	public function delete( $array ) {
-		$c                          = $this->c;
-		$c->headers['Content-Type'] = "application/x-www-form-urlencoded";
+		$headers = array(
+			'Content-Type' => "application/x-www-form-urlencoded"
+		);
 
 		$array['action'] = 'delete';
 		$array['format'] = 'php';
 
-		$apiResult = $c->post( $this->api, $array );
+		$apiResult = $this->session->post( $this->api, $headers, $array );
 
 		return unserialize( $apiResult );
 	}

composer.json

@@ -1,21 +1,22 @@
 {
-    "name"        : "hamstar/Wikimate",
-    "type"        : "library",
-    "description" : "Wikimate is a wrapper for the MediaWiki API that aims to be very easy to use.",
-
-    "authors" : [
+    "name": "hamstar/wikimate",
+    "type": "library",
+    "description": "Wikimate is a wrapper for the MediaWiki API that aims to be very easy to use.",
+    "license": "MIT",
+    "homepage": "https://github.com/hamstar/Wikimate",
+    "authors": [
         {
-            "homepage" : "https://github.com/hamstar"
+            "name": "Robert McLeod",
+            "email": "[email protected]",
+            "homepage": "https://github.com/hamstar"
         }
     ],
-
-    "autoload" : {
-        "classmap" : [
+    "autoload": {
+        "classmap": [
             "Wikimate.php"
         ]
     },
-
-    "require" : {
-        "shuber/curl" : "dev-master"
+    "require": {
+        "rmccue/requests": "1.*"
     }
-}
+}