Update README
This commit is contained in:
PJ Dietz
parent
1a21b2b7d0
commit
891f86f024
52
README.md
52
README.md
|
|
@ -1,20 +1,19 @@
|
|||
WellRESTed
|
||||
==========
|
||||
|
||||
WellRESTed is a microframework for creating RESTful APIs in PHP. It provides a lightwight yet powerful routing system and classes to make working with HTTP requests and responses clean and easy.
|
||||
WellRESTed is a microframework for creating RESTful APIs in PHP. It provides a lightweight yet powerful routing system and classes to make working with HTTP requests and responses clean and easy.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
- PHP 5.3
|
||||
- [Composer](http://getcomposer.org/) for autoloading
|
||||
- [PHP cURL](http://php.net/manual/en/book.curl.php) for making requests
|
||||
- [PHP cURL](http://php.net/manual/en/book.curl.php) for making requests with the `Client` class
|
||||
|
||||
|
||||
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:
|
||||
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
|
||||
{
|
||||
|
|
@ -31,7 +30,7 @@ $ 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`
|
||||
You can now use WellRESTed by including the `vendor/autoload.php` file generated by Composer.
|
||||
|
||||
|
||||
Examples
|
||||
|
|
@ -39,7 +38,7 @@ Examples
|
|||
|
||||
### Routing
|
||||
|
||||
WellRESTed's primary goal is to facilitate mapping of URIs to classes that will provide or accept representations. To do this, create a Router instance and load it up with some Routes. Each Route is simply a mapping of a URI pattern to a class name. The class name represents the Handler (any class implementing `HandlerInterface`) which the router will dispatch at the time it receives a request for the given URI. **The handlers are never loaded unless they are needed.**
|
||||
WellRESTed's primary goal is to facilitate mapping of URIs to classes that will provide or accept representations. To do this, create a `Router` instance and load it up with some `Route`s. Each `Route` is simply a mapping of a URI pattern to a class name. The class name represents the `Handler` (any class implementing `HandlerInterface`) which the router will dispatch when it receives a request for the given URI. **The handlers are never instantiated or loaded unless they are needed.**
|
||||
|
||||
Here's an example of a Router that will handle two URIs:
|
||||
|
||||
|
|
@ -97,32 +96,32 @@ For most cases, you'll want to use a subclass of the `Handler` class, which prov
|
|||
|
||||
If your endpoint should reject particular verbs, no worries. The Handler base class defines the default verb-handling methods to respond with a **405 Method Not Allowed** status.
|
||||
|
||||
Here's a simple Handler that matches the first endpoint, `/things/`.
|
||||
Here's a simple Handler that matches the first endpoint, `/cats/`.
|
||||
|
||||
```php
|
||||
class CatsCollectionHandler extends \pjdietz\WellRESTed\Handler
|
||||
{
|
||||
protected function get()
|
||||
{
|
||||
// Read some things from the database, cache, whatever.
|
||||
// ...read this into the variable $cat
|
||||
// Read some cats from the database, cache, whatever.
|
||||
// ...read these an array as the variable $cats.
|
||||
|
||||
// Set the values for the instance's response member. This is what the
|
||||
// Router will eventually use to output a response to the client.
|
||||
// Router will eventually output to the client.
|
||||
$this->response->setStatusCode(200);
|
||||
$this->response->setHeader('Content-Type', 'application/json');
|
||||
$this->response->setBody(json_encode($cat));
|
||||
$this->response->setHeader("Content-Type", "application/json");
|
||||
$this->response->setBody(json_encode($cats));
|
||||
}
|
||||
|
||||
protected function post()
|
||||
{
|
||||
// Read from the instance's request member and store a new cat.
|
||||
$cat = json_decode($this->request->getBody());
|
||||
// ...store $cat to database...
|
||||
// ...store $cat to the database...
|
||||
|
||||
// Build a response to send to the client.
|
||||
$this->response->setStatusCode(201);
|
||||
$this->response->setBody('You added a new cat!');
|
||||
$this->response->setBody(json_encode($cat));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -130,43 +129,44 @@ class CatsCollectionHandler extends \pjdietz\WellRESTed\Handler
|
|||
This Handler works with the endpoint, `/cats/{id}`. The template for this endpoint has the variable `{id}` in it. The Handler can access path variables through its `args` member, which is an associative array of variables from the URI.
|
||||
|
||||
```php
|
||||
class ThingItemHandler extends \pjdietz\WellRESTed\Handler
|
||||
class CatItemHandler extends \pjdietz\WellRESTed\Handler
|
||||
{
|
||||
protected function get()
|
||||
{
|
||||
// Lookup a cat ($cat) based on $this->args['id']
|
||||
// Find a cat ($cat) based on $this->args["id"]
|
||||
// ...do lookup here...
|
||||
|
||||
if ($cat) {
|
||||
// The cat exists! Let's output a representation.
|
||||
$this->response->setStatusCode(200);
|
||||
$this->response->setHeader('Content-Type', 'application/json');
|
||||
$this->response->setHeader("Content-Type", "application/json");
|
||||
$this->response->setBody(json_encode($cat));
|
||||
} else {
|
||||
// The ID did not match anything.
|
||||
$this->response->setStatusCode(404);
|
||||
$this->response->setHeader('Content-Type', 'text/plain');
|
||||
$this->response->setBody('No cat with id ' . $this->args['id']);
|
||||
$this->response->setHeader("Content-Type", "text/plain");
|
||||
$this->response->setBody("No cat with id " . $this->args["id"]);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Responses
|
||||
|
||||
### Requests and Responses
|
||||
|
||||
You've already seen a `Response` in use in the examples above. You can also use `Response`s outside of `Handler`s. Let's take a look at creating a new `Response`, setting a header, supplying the body, and outputting.
|
||||
You've already seen a `Response` in use in the examples above. You can also a `Response` outside of `Handler`. Let's take a look at creating a new `Response`, setting a header, supplying the body, and outputting.
|
||||
|
||||
```php
|
||||
$resp = new \pjdietz\WellRESTed\Response();
|
||||
$resp->setStatusCode(200);
|
||||
$resp->setHeader('Content-type', 'text/plain');
|
||||
$resp->setBody('Hello world!');
|
||||
$resp->setHeader("Content-type", "text/plain");
|
||||
$resp->setBody("Hello world!");
|
||||
$resp->respond();
|
||||
exit;
|
||||
```
|
||||
|
||||
The `Request` class goes hand-in-hand with the `Response` class. Again, this is used in the Handler class to read the information from the request being handled. From outside the context of a `Handler`, you can also use the `Request` class to read info for the request sent to the server.
|
||||
### Requests
|
||||
|
||||
From outside the context of a `Handler`, you can also use the `Request` class to read info for the request sent to the server by using the static method `Request::getRequest()`.
|
||||
|
||||
```php
|
||||
// Call the static method Request::getRequest() to get a reference to the Request
|
||||
|
|
@ -182,7 +182,7 @@ if ($rqst->getMethod() === 'PUT') {
|
|||
|
||||
### HTTP Client
|
||||
|
||||
You can also use the `Client` class to make a request using cURL.
|
||||
The `Client` class allows you to make an HTTP request using cURL.
|
||||
|
||||
(This feature requires [PHP cURL](http://php.net/manual/en/book.curl.php).)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue