From be9bca1d5aeb797f43b82293fa50fa3f91b49107 Mon Sep 17 00:00:00 2001 From: Ahmad Nassri Date: Wed, 14 Jan 2015 18:31:21 -0500 Subject: [PATCH] splitting out Unirest\File and updating README --- README.md | 82 +++++++++++++++++------------------ src/Unirest.php | 1 + src/Unirest/File.php | 19 ++++++++ src/Unirest/Method.php | 3 -- src/Unirest/Request.php | 13 ------ src/Unirest/Response.php | 4 +- tests/Unirest/RequestTest.php | 8 ++-- 7 files changed, 64 insertions(+), 66 deletions(-) create mode 100644 src/Unirest/File.php diff --git a/README.md b/README.md index ffff4a9..6a06281 100644 --- a/README.md +++ b/README.md @@ -2,38 +2,38 @@ Unirest is a set of lightweight HTTP libraries available in multiple languages, ideal for most applications: -* Make `GET`, `POST`, `PUT`, `PATCH`, `DELETE` requests -* It supports form parameters, file uploads and custom body entities +* Utility methods to call `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH` requests +* Supports form parameters, file uploads and custom body entities * Supports gzip * Supports Basic Authentication natively * Customizable timeout * Customizable default headers for every request (DRY) * Automatic JSON parsing into a native object for JSON responses -Created with love by [thefosk](https://github.com/thefosk) @ [mashape.com](https://mashape.com) +Created with love by [Mashape](https://www.mashape.com) --- -**To the community**: At this time Unirest-PHP only support syncronous requests, and I would really love to implement asynchronous support. If you guys have any feedback or ideas please comment on issue #23. +**To the community**: At this time Unirest-PHP only support syncronous requests, and I would really love to implement asynchronous support. If you guys have any feedback or ideas please comment on issue [#23](https://github.com/Mashape/unirest-php/issues/23). --- ### Install with Composer -If you're using [Composer](https://github.com/composer/composer) to manage -dependencies, you can add Unirest with it. +If you're using [Composer](https://getcomposer.org/) to manage dependencies, you can add Unirest with it. ```javascript { "require" : { - "mashape/unirest-php" : "dev-master" + "mashape/unirest-php" : "2.0.*" }, "autoload": { - "psr-0": {"Unirest": "lib/"} + "psr-0": {"Unirest": "src/"} } } ``` ### Install source from GitHub + Unirest-PHP requires PHP `v5.3+`. Download the PHP library from Github, and require in your script like so: To install the source code: @@ -45,7 +45,7 @@ $ git clone git@github.com:Mashape/unirest-php.git And include it in your scripts: ```bash -require_once '/path/to/unirest-php/lib/Unirest.php'; +require_once '/path/to/unirest-php/src/Unirest.php'; ``` ## Creating Request @@ -53,17 +53,15 @@ require_once '/path/to/unirest-php/lib/Unirest.php'; So you're probably wondering how using Unirest makes creating requests in PHP easier, let's look at a working example: ```php -$response = Unirest::post("http://httpbin.org/post", array( "Accept" => "application/json" ), - array( - "parameter" => 23, - "foo" => "bar" - ) -); +$headers = array("Accept" => "application/json"); +$body = array("foo" => "hellow", "bar" => "world"); -$response->code; // HTTP Status code -$response->headers; // Headers -$response->body; // Parsed body -$response->raw_body; // Unparsed body +$response = Unirest\Request::post("http://httpbin.org/post", $headers, $body); + +$response->code; // HTTP Status code +$response->headers; // Headers +$response->body; // Parsed body +$response->raw_body; // Unparsed body ``` ### File Uploads @@ -71,24 +69,20 @@ $response->raw_body; // Unparsed body To upload files in a multipart form representation use the return value of `Unirest::file($path)` as the value of a parameter: ```php -$response = Unirest::post("http://httpbin.org/post", array( "Accept" => "application/json" ), - array( - "file" => Unirest::file("/tmp/file.txt") // Tells Unirest where the file is located - ) -); +$headers = array("Accept" => "application/json"); +$body = array("file" => Unirest\File::add("/tmp/file.txt")); + +$response = Unirest\Request::post("http://httpbin.org/post", $headers, $body); ``` ### Custom Entity Body + Sending a custom body such as a JSON Object rather than a string or form style parameters we utilize json_encode for the body: ```php -$response = Unirest::post("http://httpbin.org/post", array( "Accept" => "application/json" ), - json_encode( - array( - "parameter" => "value", - "foo" => "bar" - ) - ) -); +$headers = array("Accept" => "application/json"); +$body = json_encode(array("foo" => "hellow", "bar" => "world")); + +$response = Unirest\Request::post("http://httpbin.org/post", $headers, $body); ``` ### Basic Authentication @@ -96,16 +90,17 @@ $response = Unirest::post("http://httpbin.org/post", array( "Accept" => "applica Authenticating the request with basic authentication can be done by providing the `username` and `password` arguments: ```php -$response = Unirest::get("http://httpbin.org/get", null, null, "username", "password"); +$response = Unirest\Request::get("http://httpbin.org/get", null, null, "username", "password"); ``` # Request + ```php -Unirest::get($url, $headers = array(), $parameters = NULL, $username = NULL, $password = NULL) -Unirest::post($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) -Unirest::put($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) -Unirest::patch($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) -Unirest::delete($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) +Unirest\Request::get($url, $headers = array(), $parameters = NULL, $username = NULL, $password = NULL) +Unirest\Request::post($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) +Unirest\Request::put($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) +Unirest\Request::patch($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) +Unirest\Request::delete($url, $headers = array(), $body = NULL, $username = NULL, $password = NULL) ``` - `url` - Endpoint, address, or uri to be acted upon and requested information from. @@ -115,6 +110,7 @@ Unirest::delete($url, $headers = array(), $body = NULL, $username = NULL, $passw - `password` - Basic Authentication password # Response + Upon recieving a response Unirest returns the result in the form of an Object, this object should always have the same keys for each language regarding to the response details. - `code` - HTTP Response Status Code (Example `200`) @@ -131,7 +127,7 @@ You can set some advanced configuration to tune Unirest-PHP: You can set a custom timeout value (in **seconds**): ```php -Unirest::timeout(5); // 5s timeout +Unirest\Request::timeout(5); // 5s timeout ``` ### Default Request Headers @@ -139,14 +135,14 @@ Unirest::timeout(5); // 5s timeout You can set default headers that will be sent on every request: ```php -Unirest::defaultHeader("Header1", "Value1"); -Unirest::defaultHeader("Header2", "Value2"); +Unirest\Request::defaultHeader("Header1", "Value1"); +Unirest\Request::defaultHeader("Header2", "Value2"); ``` You can clear the default headers anytime with: ```php -Unirest::clearDefaultHeaders(); +Unirest\Request::clearDefaultHeaders(); ``` ### SSL validation @@ -154,7 +150,7 @@ Unirest::clearDefaultHeaders(); You can explicitly enable or disable SSL certificate validation when consuming an SSL protected endpoint: ```php -Unirest::verifyPeer(false); // Disables SSL cert validation +Unirest\Request::verifyPeer(false); // Disables SSL cert validation ``` By default is `true`. diff --git a/src/Unirest.php b/src/Unirest.php index a2d0a5a..a75eb85 100644 --- a/src/Unirest.php +++ b/src/Unirest.php @@ -1,5 +1,6 @@ $h) { $h = explode(':', $h, 2); diff --git a/tests/Unirest/RequestTest.php b/tests/Unirest/RequestTest.php index f6c835b..c1cc523 100644 --- a/tests/Unirest/RequestTest.php +++ b/tests/Unirest/RequestTest.php @@ -4,11 +4,11 @@ require_once __DIR__ . '/../../src/Unirest.php'; define('UPLOAD_FIXTURE', dirname(__DIR__) . '/fixtures/upload.txt'); +use Unirest\File as File; use Unirest\Request as Request; class UnirestTest extends \PHPUnit_Framework_TestCase { - public function testGet() { $response = Request::get('http://httpbin.org/get?name=Mark', array( @@ -197,7 +197,7 @@ class UnirestTest extends \PHPUnit_Framework_TestCase public function testHttpBuildQueryWhenCurlFile() { - $file = Request::file(UPLOAD_FIXTURE); + $file = File::add(UPLOAD_FIXTURE); $body = array( 'to' => 'mail@mailinator.com', 'from' => 'mail@mailinator.com', @@ -214,7 +214,7 @@ class UnirestTest extends \PHPUnit_Framework_TestCase 'Accept' => 'application/json' ), array( 'name' => 'Mark', - 'file' => Request::file(UPLOAD_FIXTURE) + 'file' => File::add(UPLOAD_FIXTURE) )); $this->assertEquals(200, $response->code); @@ -231,7 +231,7 @@ class UnirestTest extends \PHPUnit_Framework_TestCase 'Accept' => 'application/json' ), array( 'name' => 'Mark', - 'files[owl.gif]' => Request::file(UPLOAD_FIXTURE) + 'files[owl.gif]' => File::add(UPLOAD_FIXTURE) )); $this->assertEquals(200, $response->code);