Merge pull request #4 from MASNathan/v2.0.0

V2.0.0 - HTTPlug all the way

.gitattributes

@@ -0,0 +1,3 @@
+/examples           export-ignore
+.gitattributes      export-ignore
+.gitignore          export-ignore

.gitignore

@@ -1,2 +1,4 @@
-vendor/*
-*.lock
+.idea
+
+vendor
+*.lock

README.md

@@ -1,4 +1,4 @@
-#APIcaller 
+# APIcaller 
 
 [![Downloads with Composer](https://poser.pugx.org/masnathan/api-caller/downloads.png)](https://packagist.org/packages/masnathan/api-caller)
 [![SensioLabs Insight](https://insight.sensiolabs.com/projects/a1bfb7a8-0b34-4118-a451-fc8f158ef9c7/mini.png)](https://insight.sensiolabs.com/projects/6d9231d8-9140-4b02-9522-5d3c3aa3d6f2)
@@ -7,69 +7,103 @@
 APIcaller is a class that helps you build API wrappers.  
 You don't have to worry about building URLs, or even about parsing the requested data.
 
-# How to install via Composer
+## How to use
 
-The recommended way to install is through [Composer](http://composer.org).
+You will have to extend the ```Client``` class and the ```Caller``` class, the ```Client``` will handle all the 
+configuration to use on the requests and the ```Caller``` will be used as the interface to interact with the API.
 
-```sh
-# Install Composer
-$ curl -sS https://getcomposer.org/installer | php
+```php
+use MASNathan\APICaller\Client;
+use MASNathan\APICaller\Caller;
 
-# Add APIcaller as a dependency
-$ php composer.phar require masnathan/api-caller:dev-master
-```
+class MyPackageClient extends Client
+{
+    /**
+     * Here you can set the default headers and parameters on a global scope
+     */
+    public function __construct($ip = null)
+    {
+        $this->setDefaultHeaders([
+            'User-Agent' => 'PHP APICaller SDK',
+            'Accept'     => 'application/json',
+            'Token'      => '123456',
+        ]);
+        $this->setDefaultParameters([
+            'ip' => $ip ?: '127.0.0.1',
+        ]);
+    }
+
+    /**
+     * Returns the API Endpoint
+     *
+     * @return string
+     */
+    public function getEndpoint()
+    {
+        return 'http://api.domain.com/v1/';
+    }
+}
 
-Once it's installed, you need to require Composer's autoloader:
+class MyPackageCaller extends Caller
+{
+    public function requestSomething($foo, $bar)
+    {
+        $params = [
+            'foo' => $foo,
+            'bar' => $bar,
+        ];
 
-```php
-require 'vendor/autoload.php';
-```
+        // this will result in this url http://api.domain.com/v1/some-method.json?ip={$ip}&foo={$foo}&bar={$bar}
+        $response = $this->client->get('some-method.json', $params);
 
-#How to Extend
-Here is some quick example.
+        $data = $this->handleResponseContent($response, 'json');
 
-```php
-class MyClass extends APIcaller
-{
-	function __construct()
-	{
-	    /*
-	     * Calling the parent construct you can send the API URL, set the request method and/or the response type
-	     * The API URL must be a valid url
-       	 * The Request Method to use [GET|POST|PUT|DELETE], we have constants APIcaller::METHOD_GET, APIcaller::METHOD_…
-       	 * The format of the data the webservice will return, can be APIcaller::CONTENT_TYPE_NONE, APIcaller::CONTENT_TYPE_JSON or APIcaller::CONTENT_TYPE_XML
-	     */
-		parent::__construct('http://www.some_api.com/', APIcaller::METHOD_GET, 'json');
-
-		//You can also set some default parameters to use on the calls, like api keys and such.
-		$this->setDefault('api_key', 'key');
-	}
-
-	/****/
+        // Do something with your data
+
+        return $data;
+    }
 }
 ```
 
 Well, this is how you can start creating your class, now, lets make some calls!
 
 ```php
-public function callMeBaby($some_number)
-{   
-    //1st, you need to set the parameters you want to send
-    $params = array(
-            'number' => $some_number,
-            'other'  => 'info',
-        );
-    //2nd, you send the request
-    return $this->call('call_a_friend', $params);
-}
+$client = new MyPackageClient('8.8.8.8');
+$caller = new MyPackageCaller($client);
+
+$result = $caller->requestSomething(13, 37);
+
+var_dump($result);
 ```
 
-This function will call the following url:```http://www.some_api.com/call_a_friend?api_key=key&number=1&other=info```.
+This will call the following url:```http://api.domain.com/v1/some-method.json?ip=8.8.8.8&foo=13&bar=37```.
+
+## Installation
+
+To install the SDK, you will need to be using [Composer](http://composer.org) in your project. If you don't have composer 
+installed check this page and follow the [installation steps](https://getcomposer.org/download/)
 
-If you set the format/ response type to ```json``` or ```xml``` and the response has a valid format, the ```$this->call()```function will return an array with the parsed data, if not, it'll return a string of the response.
+This library is not hard coupled to Guzzle or any other library that sends HTTP messages. 
+It uses an abstraction called [HTTPlug](http://httplug.io/). 
+This will give you the flexibility to choose what PSR-7 implementation and HTTP client to use.
+
+To get started ASAP you should run the following command:
+
+```sh
+# Add APIcaller as a dependency
+$ composer require masnathan/api-caller php-http/curl-client guzzlehttp/psr7
+```
+
+## Why do I need to require all those packages?
+
+APICaller depends on the virtual package [php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation) 
+which requires to you install an adapter, but we do not care which one. 
+That is an implementation detail in your application. 
+We also need a PSR-7 implementation and a message factory.
+
+You don't have to use the [php-http/curl-client](https://github.com/php-http/curl-client) if you don't want to. 
+Read more about the virtual packages, why this is a good idea and about the flexibility it brings at the [HTTPlug docs](http://docs.php-http.org/en/latest/index.html).
 
 # License
 
 This library is under the MIT License, see the complete license [here](LICENSE)
-
-###Is your project using `APIcaller`? [Let me know](https://github.com/ReiDuKuduro/APIcaller/issues/new?title=New%20script%20using%20APIcaller&body=Name and Description of your script.)!

composer.json

@@ -1,24 +1,37 @@
 {
-    "name": "masnathan/api-caller",
-    "type": "library",
-    "description": "Calling APIs made easy.",
-    "keywords": ["api","webservice","request","curl"],
-    "homepage": "https://github.com/ReiDuKuduro/APIcaller",
-    "license": "MIT",
-    "authors": [
-        {
-            "name": "André Filipe",
-            "email": "andre.r.flip@gmail.com",
-            "role": "Developer"
-        }
-    ],
-    "require": {
-        "php": ">=5.3.0",
-        "masnathan/curl": "0.0.2"
-    },
-    "autoload": {
-        "psr-0": {
-            "MASNathan\\APIcaller\\": "src/"
-        }
+  "name": "masnathan/api-caller",
+  "type": "library",
+  "description": "Calling APIs made easy.",
+  "keywords": [
+    "api",
+    "webservice",
+    "request"
+  ],
+  "homepage": "https://github.com/MASNathan/APICaller",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "André Filipe",
+      "email": "andre.r.flip@gmail.com",
+      "role": "Developer"
     }
+  ],
+  "require": {
+    "php": ">=5.6",
+    "php-http/client-implementation": "^1.0",
+    "php-http/client-common": "^1.2",
+    "php-http/discovery": "^1.0",
+    "masnathan/parser": "^0.0.1"
+  },
+  "require-dev": {
+    "php-http/mock-client": "^1.0.1",
+    "guzzlehttp/psr7": "^1.0",
+    "php-http/curl-client": "^1.6",
+    "symfony/var-dumper": "^3.1"
+  },
+  "autoload": {
+    "psr-4": {
+      "MASNathan\\APICaller\\": "src/"
+    }
+  }
 }

examples/GeoPlugin.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace MASNathan\GeoPlugin;
+
+use MASNathan\APICaller\Caller;
+
+/**
+ * GeoPlugin - API Wrapper for http://www.geoplugin.com/,
+ * Simple example on How to use the APIcaller class to call an API
+ *
+ * @author    André Filipe <andre.r.flip@gmail.com>
+ */
+class GeoPlugin extends Caller
+{
+
+    /**
+     * Fetches the IP locatio info
+     *
+     * @param string $ip
+     * @param string $baseCurrency i.e.: "EUR"
+     * @return array
+     */
+    public function getLocation($ip = '', $baseCurrency = '', $renameArrayKeys = false)
+    {
+        $params = [
+            'ip'            => !$ip ? $_SERVER['REMOTE_ADDR'] : $ip,
+            'base_currency' => $baseCurrency,
+        ];
+
+        $response = $this->client->get('json.gp', $params);
+
+        $data = $this->handleResponseContent($response, 'json');
+
+        if ($renameArrayKeys) {
+            $tmpData = [];
+            foreach ($data as $key => $value) {
+                $tmpData[str_replace('geoplugin_', '', $key)] = $value;
+            }
+            $data = $tmpData;
+        }
+
+        return $data;
+    }
+}

examples/GeoPluginClient.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace MASNathan\GeoPlugin;
+
+use MASNathan\APICaller\Client;
+
+/**
+ * Geoplugin - API Wrapper for http://www.geoplugin.com/,
+ * Simple example on How to use the APIcaller class to call an API
+ *
+ * @author    André Filipe <andre.r.flip@gmail.com>
+ */
+class GeoPluginClient extends Client
+{
+    public function __construct()
+    {
+        parent::__construct();
+
+        $this->setHeaders([
+            'Accept' => 'application/json',
+        ]);
+    }
+
+    public function getEndpoint()
+    {
+        return 'http://www.geoplugin.net/';
+    }
+}

examples/Geoplugin.md

@@ -7,13 +7,14 @@ API used: http://www.geoplugin.com/
 ##How to use this class:
 ```php
 //Initializing the caller
-$geo = new MASNathan\Geoplugin\Geoplugin();
+$client = new MASNathan\Geoplugin\GeoPluginClient();
+$geo = new MASNathan\Geoplugin\Geoplugin($client);
 
 //Getting IP info
 $geo->getLocation('173.194.41.223');
 $geo->getLocation('173.194.41.223', 'EUR', true);
 $geo->getLocation('173.194.41.223', 'USD', true);
 
-//Get the last call to the API
-$geo->getLastCall();
-```
+//Get the last request and response to the API
+var_dump($geo->getLastOperation());
+```