WellRESTed
==========

WellRESTed provides classes to help you create RESTful APIs and work with HTTP requests and responses.



Requirements
------------

- PHP 5.3
- [Composer](http://getcomposer.org/) for autoloading
- [PHP cURL](http://php.net/manual/en/book.curl.php) for making requests



Install
-------

Add an entry for "pjdietz/wellrested" to your composer.json file's **require** property. If you are not already using Composer, create a file in your project called **composer.json** with the following content:

```json
{
    "require": {
        "pjdietz/wellrested": "dev-master"
    }
}
```

Use Composer to download and install WellRESTed. Run these commands from the directory containing the composer.json file.

```bash
$ curl -s https://getcomposer.org/installer | php
$ php composer.phar install
```

You can now use WellRESTed by including the autoload.php file generated by Composer. (vendor/autoload.php)



Examples
--------

### Responses

Use a Response instance to build a response and send output. The Request class makes it easy to set the status code, add headers, and set the response body.

```php
$resp = new \pjdietz\WellRESTed\Response();
$resp->statusCode = 200;
$resp->setHeader('Content-type', 'text/plain');
$resp->body = 'Hello world!';
$resp->respond();
exit;
```

### Requests

Use the Request class read information about the request sent to the server. You can ready the headers, method, and message body.

Request provides a singlton instance representing the request sent to the current script.

```php
$rqst = \pjdietz\WellRESTed\Request::getRequest();

if ($rqst->method === 'PUT') {
    $obj = json_decode($rqst->body);
    // Do something with the JSON sent as the message body.
}
```

The Request class can also make a request to another server and provide the response as a Respones object. (This feature requires [PHP cURL](http://php.net/manual/en/book.curl.php).)

```php
// Prepare a request.
$rqst = new \pjdietz\WellRESTed\Request();
$rqst->uri = 'http://my.api.local/resources/';
$rqst->method = 'POST';
$rqst->body = json_encode($newResource);

// Make the request.
$resp = $rqst->request();

// Read the response.
if ($resp->statusCode === 201) {
    // The new resource was created.
    $newResource = json_decode($resp->body);
}
```

### URIs and Routing

WellRESTed also provides several classes to facilitate working with resource-based URIs. You can create your own regular expressions to match the URIs, or you can use URI templates.

Here's an example of a Router subclass which examines the request URI, compares it against a series of URI templates, and matches the request to a particular Handler class.

For more information on URI templates, see [RFC 6570](http://tools.ietf.org/html/rfc6570).

```php
/**
 * Loads and instantiates handlers based on URI.
 */
class MyRouter extends \pjdietz\WellRESTed\Router
{
    public function __construct()
    {
        parent::__construct();

        // Match any request to the URI "/things/"
        // Send it to a handler to collections of thing objects.
        $this->addRoute(Route::newFromUriTemplate('/things/', 'ThingCollectionHandler'));

        // Match any request to "/things/" followed by a variable.
        // Send the request to a handler for one thing object.
        // The ThingItemHandler will receive an array containing an "id" key
        // and the value from the URI.
        $this->addRoute(Route::newFromUriTemplate('/things/{id}', 'ThingItemHandler'));

        // ...Add as manu routes as you like here...
    }
}

```

More explamples
---------------

For more examples, see the project [pjdietz/wellrested-samples](https://github.com/pjdietz/wellrested-samples).