README

REST_Client
===========

Description
-----------

A simple and flexible REST client which uses PHP's Curl extension to send 
optimized HTTP queries. It has been specially designed to query a REST server.

This package can be used to:
  - send synchronous requests 
    using REST_EasyClient or REST_Client_Sync classes,
  - or send huge quantities but optimized asynchronous requests 
    using REST_Client_Async class.


Installation
------------

pear channel-discover pear.pxxo.net
pear install pxxo/REST_Client


Usage
-----

<?php

require_once 'REST/Client.php';

$rc = new  REST_EasyClient('rest.server.com', 8080);

// GET Method
$o = $rc->get('/resource/to/get');

// check network error
if ($o->isError()) die($o->error);

// check http response code
if ($o->code == 404) die('Oups, where is my resource ?');

// the content of the resource
echo $o->content;

// DELETE Method
$o = $rc->delete('/resource/to/delete');

// POST Method
// $data can be a array or a string chars
$data = array('key' => 'value');
$o = $rc->post('/resource/to/post', $data);

// PUT Method
$data = '<xml>some data</xml>';
$o = $rc->put('/resource/to/put', $data);

// Retrieve HTTP headers
echo $o->headers['x-powered-by'];
echo $o->headers['location'];

?>

Advanced usage
--------------

<?php

require_once 'REST/Client.php';

$rc = REST_Client::factory('async', array('queue_size' => 30)); // for huge request quantities
// $rc = REST_Client::factory('sync'); // for few request (but REST_EasyClient is easier to use)

$r = REST_Request::newInstance()
        ->setProtocol('http')->setHost($this->test_host)->setPort($this->test_port)
        ->setMethod('GET')->setUrl('/')
        ->setAuth('kerphi','secret')
        ->setHttpProxy(getenv('http_proxy'));

// GET Method : 5000 requests !
for($i = 0; $i < 5000; $i++) {
    $id = $rc->fire($r);
    
    // start handling results before firing is finished
    if ($i > $rc->getOption('queue_size')) {
        while($response = $rc->fetch()) {
            var_dump($response);
        }
    }
}
// continue to handle results
while($response = $rc->fetch()) {
    var_dump($response);
}

// GET Method (2)
$id = $rc->fire($r->get('/maressource'));
while($response = $rc->fetch()) {
    var_dump($response);
}

// PUT Method
$id = $rc->fire($r->put('/maressource', 'DATA'));
while($response = $rc->fetch()) {
    var_dump($response);
}

?>