Allow passing parameters as a pre-encoded string (or something that allows casting to a string). Parameters passed as strings will not be merged with parameters specified in the default options.

Update documentation with PATCH JSON recommendations.

Author: tcdent

README.markdown

@@ -52,13 +52,36 @@ Verbs
 -----
 Four HTTP verbs are implemented as convenience methods: `get()`, `post()`, `put()` and `delete()`. Each accepts three arguments:  
 
-`url` - URL of the resource you are requesting. Will be prepended with the value of the `base_url` option, if it has been configured. Will be appended with the value of the `format` option, if it has been configured.  
-`parameters` - An associative array of query parameters, which will be formatted with the URL in `GET` requests, and passed in the request body on all others.  
-`headers` - An associative array of headers to include with the request. 
+`url` - `string` URL of the resource you are requesting. Will be prepended with the value of the `base_url` option, if it has been configured. Will be appended with the value of the `format` option, if it has been configured.  
+
+`parameters` - `string` or associative `array` to be appended to the URL in `GET` requests and passed in the request body on all others. If an array is passed it will be encoded into a query string.
+
+`headers` - An associative `array` of headers to include with the request. 
 
 You can make a request using any verb by calling `execute()` directly, which accepts four arguments: `url`, `method`, `parameters` and `headers`. All arguments expect the same values as in the convenience methods, with the exception of the additional `method` argument:
 
-`method` - HTTP verb to perform the request with. 
+`method` - `string` HTTP verb to perform the request with. 
+
+
+JSON Verbs
+----------
+This library will never validate or construct `PATCH JSON` content, but it can be configured to communicate well-formed data.
+
+`PATCH JSON` content with correct content type:
+
+    $result = $api->execute("http://httpbin.org/patch", 'PATCH',
+        json_encode(array('foo' => 'bar')),
+        array(
+            'X-HTTP-Method-Override' => 'PATCH', 
+            'Content-Type' => 'application/json-patch+json'));
+
+Note that your specific endpoint may not require the `X-HTTP-Method-Override` header, nor understand the [correct](http://tools.ietf.org/html/rfc6902#section-6) `application/json-patch+json` content type. 
+
+`POST JSON` content with correct content type:
+
+    $result = $api->post("http://httpbin.org/post",
+        json_encode(array('foo' => 'bar')),
+        array('Content-Type' => 'application/json'));
 
 
 Not all endpoints support all HTTP verbs

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "tcdent/php-restclient", 
-    "version": "0.1.3", 
+    "version": "0.1.4", 
     "description": "A generic REST API client for PHP", 
     "type": "library", 
     "keywords": ["REST", "api", "client", "curl", "JSON", "XML"], 

restclient.php

@@ -28,7 +28,7 @@ public function __construct($options=array()){
             'headers' => array(), 
             'parameters' => array(), 
             'curl_options' => array(), 
-            'user_agent' => "PHP RestClient/0.1.3", 
+            'user_agent' => "PHP RestClient/0.1.4", 
             'base_url' => NULL, 
             'format' => NULL, 
             'format_regex' => "/(\w+)\/(\w+)(;[.+])?/",
@@ -145,18 +145,27 @@ public function execute($url, $method='GET', $parameters=array(), $headers=array
         if($client->options['format'])
             $client->url .= '.'.$client->options['format'];
 
-        $parameters = array_merge($client->options['parameters'], $parameters);
+        // Allow passing parameters as a pre-encoded string (or something that
+        // allows casting to a string). Parameters passed as strings will not be
+        // merged with parameters specified in the default options.
+        if(is_array($parameters)){
+            $parameters = array_merge($client->options['parameters'], $parameters);
+            $paraeters_string = $client->format_query($parameters);
+        }
+        else
+            $paraeters_string = (string) $parameters;
+        
         if(strtoupper($method) == 'POST'){
             $curlopt[CURLOPT_POST] = TRUE;
-            $curlopt[CURLOPT_POSTFIELDS] = $client->format_query($parameters);
+            $curlopt[CURLOPT_POSTFIELDS] = $paraeters_string;
         }
         elseif(strtoupper($method) != 'GET'){
             $curlopt[CURLOPT_CUSTOMREQUEST] = strtoupper($method);
-            $curlopt[CURLOPT_POSTFIELDS] = $client->format_query($parameters);
+            $curlopt[CURLOPT_POSTFIELDS] = $paraeters_string;
         }
-        elseif(count($parameters)){
+        elseif($parameters_string){
             $client->url .= strpos($client->url, '?')? '&' : '?';
-            $client->url .= $client->format_query($parameters);
+            $client->url .= $parameters_string;
         }
 
         if($client->options['base_url']){