3.8 KiB

Raw Blame History

WellRESTed

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

Requirements

PHP 5.3
Composer for autoloading
PHP cURL 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:

{
    "require": {
        "pjdietz/wellrested": "1.*"
    }
}

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

$ 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 Response class makes it easy to set the status code, add headers, and set the response body.

$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 to read information about the request sent to the server. You can read the headers, method, and message body.

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

$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.)

// 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. The subclass examines a 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.

/**
 * 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 for 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 Examples

For more examples, see the project pjdietz/wellrested-samples.

3.8 KiB Raw Blame History