README

A bundle for integrating tbbc/rest-util lib in a Symfony application

Table of contents

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

Installation

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

{ "require": { "tbbc/rest-util-bundle": "@stable" } }

Quick start

Handling errors in a REST(ful) API

#### Configuration

tbbc_rest_util: error: use_bundled_factories: true exception_mapping: FormErrorException: class: "Tbbc\\RestUtilBundle\\Error\\Exception\\FormErrorException" factory: tbbc_rest_util_form_error http_status_code: 400 error_code: 400101 error_message: "Invalid input" error_more_info_url: "http://api.my.tld/doc/error/400101" AccessDeniedException: class: "Symfony\\Component\\Security\\Core\\AccessDeniedException" factory: default http_status_code: 401 error_code: 401001 error_message: "Access denied" extended_message: "The given token don't have enough privileges for accessing to this resource" error_more_info_url: "http://api.my.tld/doc/error/401001" CustomException: class: "My\\ApiBundle\\Exception\\CustomException" factory: my_api_custom http_status_code: 501 error_code: 501001 error_more_info_url: "http://api.my.tld/doc/error/501001" Exception: class: "\\Exception" factory: default http_status_code: 500 error_code: 501203 error_message: "Server error"

Custom Symfony Exception Listener

<?php namespace My\ApiBundle\EventListener; // ... other use statements use Tbbc\RestUtil\Error\ErrorResolverInterface; class RestExceptionListener extends ExceptionListener { private $errorResolver; public function __construct(ErrorResolverInterface $errorResolver, $controller, LoggerInterface $logger = null) { $this->errorResolver = $errorResolver; parent::__construct($controller, $logger); } /**  * @param GetResponseForExceptionEvent $event  * @return void  */ public function onKernelException(GetResponseForExceptionEvent $event) { static $handling; if (true === $handling) { return; } $exception = $event->getException(); $error = $this->errorResolver->resolve($exception); if (null == $error) { return; } $handling = true; $response = new Response(json_encode($error->toArray()), $error->getHttpStatusCode(), array( 'Content-Type' => 'application/json' )); $event->setResponse($response); } public static function getSubscribedEvents() { return array( KernelEvents::EXCEPTION => array('onKernelException', 10), ); } }

<?xml version="1.0" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd"> <parameters> <parameter key="my_api.event_listener.rest_exception.class">My\ApiBundle\EventListener\RestExceptionListener</parameter> </parameters> <services> <service id="my_api.event_listener.rest_exception" class="%my_api.event_listener.rest_exception.class%"> <tag name="kernel.event_subscriber" /> <tag name="monolog.logger" channel="request" /> <argument type="service" id="tbbc_rest_util.error.error_resolver" /> <argument>%twig.exception_listener.controller%</argument> <argument type="service" id="logger" on-invalid="null" /> </service> </services> </container>

Api Controller code

<?php namespace My\ApiBundle\Controller; // ... other use statements use Symfony\Component\Security\Core\AccessDeniedException; use Tbbc\RestUtilBundle\Error\Exception\FormErrorException; use My\ApiBundle\Exception\CustomException; class PostCommentsController extends Controller { public function postCommentsAction($postId) { // ... fetch $post with $postId if (!$this->get('security.context')->isGranted('COMMENT', $post)) { throw new AccessDeniedException('Access denied'); } $commentResource = new CommentResource(); $form = $this->createNamedForm('', new CommentResourceType(), $commentResource); $form->bind($this->getRequest()); if (!$form->isValid()) { throw new FormErrorException($form); } // another error if (....) { throw new CustomException('Something bad just happened!'); } // ... save comment or whatever } }

MyApiCustomException error factory

<?php namespace My\ApiBundle\Error\Factory; use Tbbc\RestUtil\Error\Error; use Tbbc\RestUtil\Error\ErrorFactoryInterface; use Tbbc\RestUtil\Error\Mapping\ExceptionMappingInterface; use My\ApiBundle\Exception\CustomException; class CustomErrorFactory implements ErrorFactoryInterface { /**  * {@inheritDoc}  */ public function getIdentifier() { return 'my_api_custom'; } /**  * {@inheritDoc}  */ public function createError(\Exception $exception, ExceptionMappingInterface $mapping) { if (!$this->supportsException($exception)) { return null; } $errorMessage = $mapping->getErrorMessage(); if (empty($errorMessage)) { $errorMessage = $exception->getMessage(); } $extendedMessage = $exception->getMoreExtendedMessage(); // Or whatever you need to do with your exception here return new Error($mapping->getHttpStatusCode(), $mapping->getErrorCode(), $errorMessage, $extendedMessage, $mapping->getErrorMoreInfoUrl()); } /**  * {@inheritDoc}  */ public function supportsException(\Exception $exception) { return $exception instanceof CustomException; } }

<?xml version="1.0" ?> <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd"> <parameters> <parameter key="my_api.error.custom_error_factory.class">My\ApiBundle\Error\Factory\CustomErrorFactory</parameter> </parameters> <services> <service id="my_api.error.custom_error_factory" class="%my_api.error.custom_error_factory.class%"> <tag name="tbbc_rest_util.error_factory" /> </service> </services> </container>

ENJOY!

For the exceptions thrown in the previous PostCommentsController class example, the response body will be respectively something like the following:

For the AccessDeniedException exception:

{ "http_status_code": 401, "code": 401001, "message": "Access denied", "extended_message": "The given token don't have enough privileges for accessing to this resource", "more_info_url": "http:\/\/api.my.tld\/doc\/error\/401001" }

For the FormErrorException exception:

{ "http_status_code": 400, "code": 400101, "message": "Invalid input", "extended_message": { "global_errors": [ "Bubbled form error!" ], "property_errors": { "content": [ "The comment content should not be blank", ] } }, "more_info_url": "http:\/\/api.my.tld\/doc\/error\/400101" }

For the CustomException exception:

{ "http_status_code": 501, "code": 501001, "message": "Something bad just happened!", "extended_message": null, "more_info_url": "http:\/\/api.my.tld\/doc\/error\/501001" }

Usage

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

• Benjamin Dulau - benjamin.dulau@gmail.com
• Valentin Ferriere - valentin@v-labs.fr

License

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