tbbc/rest-util

Some useful classes for handling certain aspects of a REST(ful) API.

v1.0.0 2014-05-28 12:31 UTC

Requires

• php: >=5.3.3

Requires (Dev)

• phpunit/phpunit: 3.*

MIT

• Boris Guéry
• Benjamin Dulau

• rest
• api
• restful

README

Rest util library for PHP.

This library implement some useful util classes for resolving recurrent issues in Rest(ful) APIs (i.e: Error handling).

Quick Start

Table of contents

1. Installation
2. Getting started
3. Usage
4. Run the test
5. Contributing
6. Requirements
7. Authors
8. License

Description

Rest utilitary library for PHP

Installation

Using Composer, just $ composer require tbbc/rest-util package or:

{
  "require": {
    "tbbc/rest-util": "dev-master"
  }
}

Usage

Converting Exception into Error object:

1. First you have to define an ExceptionMapping, for the sake of the example, we use PHP, but a YamlLoader is also available:

// Exception mapping configuration
$invalidArgumentExceptionMapping = new ExceptionMapping(array(
    'exceptionClassName'   => '\InvalidArgumentException',
    'factory'              => 'default',
    'httpStatusCode'       => 400,
    'errorCode'            => 400101,
    'errorMessage'         => null,
    'errorExtendedMessage' => 'Extended message',
    'errorMoreInfoUrl'     => 'http://api.my.tld/doc/error/400101',
));

2. The ExceptionMapping must be added to ExceptionMap:

$exceptionMap = new ExceptionMap();
$exceptionMap->add($invalidArgumentExceptionMapping);

3. We plug the ErrorResolver with an ErrorFactory, a DefaultErrorFactory is bundled within the lib:

// Error resolver initialization
$errorResolver       = new ErrorResolver($exceptionMap);
$defaultErrorFactory = new DefaultErrorFactory();
$errorResolver->registerFactory($defaultErrorFactory);

4. Resolve error!

$exception = new \InvalidArgumentException('This is an invalid argument exception');
$error     = $errorResolver->resolve($exception);

5. The $error variable is now assigned an ErrorInterface object which implements a toArray() method to allow easy serialization method of your choice:

print_r($error->toArray());
/* will output
Array
(
    [http_status_code] => 400
    [code]             => 400101
    [message]          => This is an invalid argument exception.
    [extended_message] => Extended message
    [more_info_url]    => http://api.my.tld/doc/error/400101
)
*/

echo json_encode($error->toArray());
/* And voilà! You get a ready to use json normalized error response body
{
    "http_status_code": 400,
    "code":             400101,
    "message":          "This is an invalid argument exception.",
    "extended_message": "Extended message",
    "more_info_url":    "http:\/\/api.my.tld\/doc\/error\/400101"
}
*/

For more concrete real life usage, take a look at our bundle for integrating the lib into a Symfony application: TbbcRestUtilBundle.

Run the test

First make sure you have installed all the dependencies, run:

$ composer install --dev

then, run the test from within the root directory:

$ vendor/bin/phpunit

Contributing

1. Take a look at the list of issues.
2. Fork
3. Write a test (for either new feature or bug)
4. Make a PR

Requirements

• PHP 5.3+

Authors

• Boris Guéry - [e-mail] - http://borisguery.com
• Benjamin Dulau - [e-mail]

License

The Big Brains Company - Rest Util is licensed under the MIT License - see the LICENSE file for details