Scurl
, (*1)
Scurl is an easy to use PHP library for making HTTP requests. It requires
PHP >= 5.4 and the curl extension. The library is PSR-0 compliant and
includes a composer file for easy inclusion in your project., (*2)
How To Include
With Composer, (*3)
Add the following to your composer.json file in your project:, (*4)
``` json
{
"require": {
"sesser/scurl": "1.*"
}
}, (*5)
Then make sure you include your `vendor/autoload.php` file.
**Without Composer**
``` php
<?php
include_once 'src/Sesser/Scurl/Scurl.php';
?>
Quick How To
Scurl is pretty basic. It supports the major calls (GET, POST, PUT, DELETE, HEAD).
At it's most basic level, you can make a GET request like so, (*6)
``` php
get('http://www.google.com');
echo $response->body;
?>, (*7)
For more complex calls like PUTting objects to servers:
``` php
<?php
$scurl = new Sesser\Scurl\Scurl;
$response = $scurl->put('http://api.awesomeapi.net/v1/upload/file.png', [], [
'data' => '/full/path/to/file.png'
]);
?>
PUTting json data (and presumably xml data, though untested) is possible too:
``` php
put('http://api.awesomeapi.net/v1/update', [ 'param' => 'value'], [
'data' => '{"data": { "foo": "bar" }}',
'headers' => ['Content-type' => 'application/json']
]);
?>, (*8)
##Events##
Scurl supports basic events too so you can make modifications to the `Request` object before it
sends the request off. Or, you can modify/read the `Response` after the request has been sent. This
could be useful for logging requests or keeping track of the time it takes to get a response from a
server.
Currently, there's only two events called; `Scurl::EVENT_BEFORE` and `Scurl::EVENT_AFTER`. They are
called before the request is sent and after the response is received, respectively. The events are a
in a stack and called from top to bottom (first in, first called) so you can assign more than one callback
to an event. See the example below:
```php
<?php
$scurl = Sesser\Scurl\Scurl::getInstance();
$after_hash = $scurl->addListener(Sesser\Scurl\Scurl::EVENT_AFTER, function(Sesser\Scurl\Request $request, Sesser\Scurl\Response $response) {
//-- Do some magic here... inspect the request headers, log the url and time it took, etc
});
?>
The Scurl::addListener method returns the pointer for this event callback. If, for some reason, you
want to remove the listener from the call stack, just call the Scurl::removeListener method., (*9)
<?php
$scurl = Sesser\Scurl\Scurl::getInstance();
$scurl->removeListener(Sesser\Scurl\Scurl::EVENT_AFTER, $after_hash);
?>
Please note that if the event passed to addListener is not a valid event or the callback is not
callable, addListener will return false indicating that failed to register the event. Also, there
is one other event that hasn't been implemented yet; Sesser\Scurl\Scurl::EVENT_ERROR. This event will
be available soon and called when there is an error at the curl level. the method signature should look
like this:, (*10)
<?php function($errNo, $errMessage, Sesser\Scurl\Request $request); ?>
The Long Story
Scurl is just a wrapper to the Request class which does most of the heavy lifting.
When you instantiate a Scurl object, you can pass an array of configuration
options. These options persist for all calls made with that object unless you
override them in a specific call. The configuration passed to the __construct
is merged with the defaults shown below:, (*11)
php
<?php
$defaults = [
'method' => Request::METHOD_GET,
'auth' => [
'user' => '',
'pass' => ''
],
'data' => '',
'parameters' => [],
'cookie' => [],
'headers' => [
'Connection' => 'keep-alive',
'Keep-Alive' => 300,
'Accept-Charset' => 'ISO-8859-1,utf-8;q=0.7,*;q=0.7',
'Accept-Language' => 'en-us,en;q=0.5'
],
'options' => [
'user-agent' => 'Scurl/1.0; PHP/' . PHP_VERSION . ' (+http://github.com/sesser/scurl)',
'timeout' => 10,
'connect_timeout' => 2,
'follow_location' => TRUE,
'max_redirects' => 3
],
];
?>, (*12)
Configuration Explained
$defaults['method']: The HTTP Method. This is generally overridden with every request, but you can set a default if you want., (*13)
$defaults['auth']: You can add your authentication credentials here or on a per-request basis by simply adding it to the $url (a la http://<user>:<pass>@somehost.com), (*14)
$defaults['data']: This is used for PUT requests, (*15)
$defaults['parameters']: Default parameters to pass in the request, (*16)
$defaults['cookie']: Set this to pass a cookie in the request. This is either a key/value pair array or a string value ('foo=bar; uid=1234'), (*17)
$defaults['headers']: Headers sent in the request., (*18)
$defaults['options']: General options, (*19)
Wallogit.com
