https://github.com/inadarei/restagent
Extremely Lightweight, powerful and intuitive HTTP client for PHP.
https://github.com/inadarei/restagent
Last synced: 6 months ago
JSON representation
Extremely Lightweight, powerful and intuitive HTTP client for PHP.
- Host: GitHub
- URL: https://github.com/inadarei/restagent
- Owner: inadarei
- Created: 2012-03-10T20:00:02.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2015-01-14T04:54:23.000Z (over 10 years ago)
- Last Synced: 2025-04-23T22:55:09.214Z (6 months ago)
- Language: PHP
- Homepage:
- Size: 691 KB
- Stars: 9
- Watchers: 10
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## RestAgent for PHP
[](https://packagist.org/packages/inadarei/restagent)
[](https://travis-ci.org/inadarei/restagent)
[](https://coveralls.io/r/inadarei/restagent?branch=master)
[](https://www.codacy.com/public/irakli/restagent)
RestAgent is an HTTP/HTTPS client library for PHP. Project's primary goals are, to:
* Provide elegant and intuitive API.
* Properly support HTTPS
* Minimize boilerplate and make working with HTTP(S) from PHP enjoyable.
* Provide rich set of functionality for RESTful interactions.
RestAgent's API is inspired by the simplicity of the API in [SuperAgent](https://github.com/visionmedia/superagent) library for Node.js by TJ Holowaychuk.
## Compatibility
PHP 5.3 or newer.
## Installation
#### 1. Install Composer
```bash
$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer
$ composer -v
```
or see detailed documentation: [https://getcomposer.org/doc/00-intro.md](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx)
#### 2. Include RestAgent in your project
Add `inadarei/restagent` to your `composer.json`.
```
{
"require": {
"inadarei/restagent": "^2.0.0"
}
}
```
Run: `composer install`
After installing, you need to require Composer's autoloader in your project files, if you are not already doing it:
```php
require_once './vendor/autoload.php';
```
## Quick Docs:
### Issuing a Request
Issue a simple HTTP GET:
$request = new \Restagent\Request;
$response = $request->get("http://example.com/user/1");
Setting base URL for requests:
$request = new \Restagent\Request('http://restagent.vm:8080/api/');
$response = $request->get("/user/1");
Little more drama, please:
$response = $request->header('Content-Type', 'application/json')
->header("X-API-Key", "aabbccdd")
->get("http://example.com/user/1");
Assemble and send an HTTP POST:
$response = $request
->header("X-API-Key", "aabbccdd")
->data(array("firstName" => "Irakli", "lastName" => "Nadareishvili"))
->data("hobby", "programming")
->header(array("User-Agent" => "RestAgent/1.0 php/libcurl", "foo" => "bar"))
->param("active", 1)
->post("http://example.com/user");
An HTTP PUT with raw data in the HTTP BODY:
$json = '{"name" : "irakli", "lastname" : "nadareishvili"}';
$response = $request
->header("X-API-Key", "aabbccdd")
->body($json)
->header(array("User-Agent" => "RestAgent/1.0 php/libcurl", "foo" => "bar"))
->put("http://example.com/user");
Using custom HTTP method and setting a custom timeout:
$response = $request
->data(array("firstName" => "Irakli", "lastName" => "Nadareishvili"))
->header("X-API-Key", "aabbccdd")
->header(array("User-Agent" => "CERN-LineMode/2.15 libwww/2.17b3"))
->method("PATCH")
->timeout(500)
->send("/user/1");
Where:
* header() sets an HTTP header
* data() sets data variable(s) to be passed during the request. It can be a query parameter in case of an HTTP GET, or
variables passed as part of HTTP body in case of HTTP POST, PUT etc.
* param() allows setting query parameters for non-HTTP GET calls (i.e. when data() would set passed variables in request
body rather than the URL). **Caution**: Do not use param() with HTTP GET or you will get an exception. Use data() instead!
More about this below.
* head(), get(), post(), put() and delete() calls issue a corresponding HTTP request.
* method() sets a custom HTTP method to be used in conjunction with a send() call.
* timeout() overrides the default timeout to a specified number of milliseconds.
Please note that data(), param() and header() methods take either an array or a single name/value pair as an argument.
Why? Because either can be convenient, in different cases.
Furthermore, methods like ->get() and ->post() are just convenience shortcuts on calling ->method("get")->send(...);
If you want to use any HTTP methods not included in the above list, try issuing ->method(...)->send();
### Why param(), again?
The purpose of the param() method can be confusing and may need further explanation.
In the puristic RESTful view, we want to have a uniform way of making HTTP calls and pass variables as we
do it. Therefore it's important, as a general rule, to be able to set request data with a uniform data() method. After
which we can make appropriate HTTP-verb call (whether it's a GET or a PUT or whatever else), without having to worry
about the specifics of the verb's way of encoding data (in the URL or HTTP Body).
That said, sometimes we do need to add HTTP query params even during an HTTP call that encodes variables in an HTTP
body (e.g. POST or PUT). Whether we consider it RESTful or not, it's allowed in HTTP and can be a necessary
"evil" sometimes. That is why param() exists: to allow for such use-cases.
However, we do not allow using param() with HTTP GET, because data() method already does what param() would do and it would
be confusing to get in the business of deciding which method gets priority or how variables are merged if somebody
decides to set the same variable through both param() and data().
That is why an attempt to use param() during an HTTP GET call results in an exception, the exception basically
indicates: "we gave you a way to shortcut the system during POST, PUT etc, now don't be asinine and don't try to
use it for GET, where you really should not be using it".
So that's the very long story of param() and its relation to data()...
### Response Format
The head(), get(), post(), put(), delete() and send() calls return an associative array that has the following structure:
* code: http response code.
* meta: a whole bunch of meta-information about the call from CURL
* data: response content for any http method except HTTP HEAD. The latter, by definition, does not return any content
so 'data' contains parsed http response headers, instead.
### CURL Debugging
By setting `REST_AGENT_DEBUG` (to any value actually):
```
export REST_AGENT_DEBUG=true
```
You can enable CURL debugging.
## License
(The MIT License)
Copyright (c) 2012-2015 Irakli Nadareishvili
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.