Add Exception configuration documentation

Author: GregoireHebert

core/errors.md

@@ -0,0 +1,203 @@
+# Error Handling
+
+API Platform Core allows to customize the HTTP status code sent to the clients when exceptions are thrown.
+
+```yaml
+# app/config/config.yml
+
+ api_platform:
+# Map exceptions to HTTP status codes using the `exception_to_status` configuration key
+    exception_to_status:
+        # The 2 following exceptions are handled by default
+        Symfony\Component\Serializer\Exception\ExceptionInterface: 400 # Use a raw status code (recommended)
+        ApiPlatform\Core\Exception\InvalidArgumentException: 'HTTP_BAD_REQUEST' # Or with a constant of `Symfony\Component\HttpFoundation\Response`
+
+        AppBundle\Exception\ProductNotFoundException: 404 # Custom exceptions can easily be handled
+```
+
+As in any php application, your exceptions have to extends the \Exception class or any of it's children.
+
+```php
+<?php
+
+// src/AppBundle/Exception/ProductNotFoundException.php
+
+namespace AppBundle\Exception;
+
+final class ProductNotFoundException extends \Exception
+{
+}
+```
+
+```php
+<?php
+
+// src/AppBundle/EventSubscriber/CartManager.php
+
+namespace AppBundle\EventSubscriber;
+
+use ApiPlatform\Core\EventListener\EventPriorities;
+use AppBundle\Entity\Product;
+use AppBundle\Exception\ProductNotFoundException;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
+use Symfony\Component\HttpKernel\KernelEvents;
+
+final class ProductManager implements EventSubscriberInterface
+{
+    private const DOESNOTEXISTS = 51;
+    private const DEACTIVATED = 52;
+    private const OUTOFSTOCK = 53;
+
+    public static function getSubscribedEvents()
+    {
+        return [
+            KernelEvents::REQUEST => [['checkProductAvailability', EventPriorities::POST_DESERIALIZE]],
+        ];
+    }
+
+    public function checkProductAvailability(GetResponseForControllerResultEvent $event)
+    {
+        $product = $event->getControllerResult();
+        $method = $event->getRequest()->getMethod();
+
+        if (!$product instanceof Product || Request::METHOD_GET !== $method) {
+            return;
+        }
+
+        if (!$product->getVirtualStock()) {
+            // Using internal codes for a better understanding of what's going on
+            throw new ProductNotFoundException(self::OUTOFSTOCK);
+        }
+    }
+}
+```
+
+The exception doesn't have to be a Symfony's `HttpException`. Any type of `Exception` can be thrown. The best part is that API Platform already takes care of how the error is handled and returned. For instance, if the API is configured to respond in JSON-LD, the error will be returned in this format as well.
+
+```json
+{
+  "@context": "/contexts/Error",
+  "@type": "Error",
+  "hydra:title": "An error occurred",
+  "hydra:description": "53"
+}
+```
+
+Is what you get, with an HTTP status code 404 as defined in the configuration.
+
+## Validation errors
+
+API Platform does handle the validation errors responses for you. You can define a Symfony supported constraint, or a custom constraint upon any `ApiResource` or it's properties.
+
+```php
+<?php
+
+// src/AppBundle/Entity/Product.php
+
+namespace AppBundle\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Validator\Constraints as Assert;
+use AppBundle\Validator\Constraints as AppAssert;
+
+/**
+ *
+ * @ApiResource
+ * @ORM\Entity
+ */
+class Product
+{
+    /**
+     * @var int The id of this product.
+     *
+     * @ORM\Id
+     * @ORM\GeneratedValue
+     * @ORM\Column(type="integer")
+     */
+    private $id;
+
+    /**
+     * @var string The name of the product
+     *
+     * @ORM\Column
+     * @Assert\NotBlank
+     */
+    private name;
+
+    /**
+     * @var ProductProperty[] Describe the product
+     *
+     * @ORM\Column(type="array")
+     * @AppAssert\MinimalProperties
+     */
+    private $properties;
+}
+```
+
+```php
+<?php
+
+// src/AppBundle/Validator/Constraints/MinimalProperties.php
+
+namespace AppBundle\Validator\Constraints;
+
+use Symfony\Component\Validator\Constraint;
+
+/**
+ * @Annotation
+ */
+class MinimalProperties extends Constraint
+{
+    public $message = 'The product must have the minimal properties required (description, price)';
+
+    public function validatedBy()
+    {
+        return get_class($this).'Validator';
+    }
+}
+```
+
+```php
+<?php
+
+// src/AppBundle/Validator/Constraints/MinimalPropertiesValidator.php
+
+namespace AppBundle\Validator\Constraints;
+
+use Symfony\Component\Validator\Constraint;
+use Symfony\Component\Validator\ConstraintValidator;
+
+/**
+ * @Annotation
+ */
+final class MinimalPropertiesValidator extends ConstraintValidator
+{
+    public function validate($value, Constraint $constraint)
+    {
+        if (!in_array('description', $value) || !in_array('price', $value)) {
+            $this->context->buildViolation($constraint->message)
+                ->addViolation();
+        }
+    }
+}
+```
+
+API Platform will handle the error returned and adapt it's format according to the API configuration. If you did configured it to respond in JSON-LD. Your response would looks like:
+
+```json
+{
+  "@context": "/contexts/ConstraintViolationList",
+  "@type": "ConstraintViolationList",
+  "hydra:title": "An error occurred",
+  "hydra:description": "properties: The product must have the minimal properties required (description, price)",
+  "violations": [
+    {
+      "propertyPath": "properties",
+      "message": "The product must have the minimal properties required (description, price)"
+    }
+  ]
+}
+```

index.md

@@ -58,27 +58,29 @@
     1.  [Using Validation Groups](core/validation.md#using-validation-groups)
     2.  [Dynamic Validation Groups](core/validation.md#dynamic-validation-groups)
     3.  [Error Levels and Payload Serialization](core/validation.md#error-levels-and-payload-serialization)
-9.  [Pagination](core/pagination.md)
+9.  [Error Handling](core/errors.md)
+    1.  [Converting PHP Exceptions to HTTP Errors](core/errors.md#converting-php-exceptions-to-http-errors)
+10.  [Pagination](core/pagination.md)
     1.  [Disabling the Pagination](core/pagination.md#disabling-the-pagination)
     2.  [Changing the Number of Items per Page](core/pagination.md#changing-the-number-of-items-per-page)
     3.  [Partial Pagination](core/pagination.md#partial-pagination)
-10.  [The Event System](core/events.md)
-11. [Content Negotiation](core/content-negotiation.md)
+11.  [The Event System](core/events.md)
+12. [Content Negotiation](core/content-negotiation.md)
     1.  [Enabling Several Formats](core/content-negotiation.md#enabling-several-formats)
     2.  [Registering a Custom Serializer](core/content-negotiation.md#registering-a-custom-serializer)
     3.  [Creating a Responder](core/content-negotiation.md#creating-a-responder)
     4.  [Writing a Custom Normalizer](core/content-negotiation.md#writing-a-custom-normalizer)
-12. [Using External JSON-LD Vocabularies](core/external-vocabularies.md)
-13. [Extending JSON-LD context](core/extending-jsonld-context.md)
-14. [Data Providers](core/data-providers.md)
+13. [Using External JSON-LD Vocabularies](core/external-vocabularies.md)
+14. [Extending JSON-LD context](core/extending-jsonld-context.md)
+15. [Data Providers](core/data-providers.md)
     1.  [Custom Collection Data Provider](core/data-providers.md#custom-collection-data-provider)
     2.  [Custom Item Data Provider](core/data-providers.md#custom-item-data-provider)
     3.  [Injecting the Serializer in an `ItemDataProvider`](core/data-providers.md#injecting-the-serializer-in-an-itemdataprovider)
-15. [Extensions](core/extensions.md)
+16. [Extensions](core/extensions.md)
     1.  [Custom Extension](core/extensions.md#custom-extension)
     2.  [Filter upon the current user](core/extensions.md#example)
-16. [Security](core/security.md)
-17. [Performance](core/performance.md)
+17. [Security](core/security.md)
+18. [Performance](core/performance.md)
     1.  [Enabling the Builtin HTTP Cache Invalidation System](core/performance.md#enabling-the-builtin-http-cache-invalidation-system)
     2.  [Enabling the Metadata Cache](core/performance.md#enabling-the-metadata-cache)
     3.  [Using PPM (PHP-PM)](core/performance.md#using-ppm-php-pm)
@@ -90,35 +92,35 @@
             3.  [Override at Resource and Operation Level](core/performance.md#override-at-resource-and-operation-level)
             4.  [Disable Eager Loading](core/performance.md#disable-eager-loading)
         3.  [Partial Pagination](core/performance.md#partial-pagination)
-18. [Operation Path Naming](core/operation-path-naming.md)
+19. [Operation Path Naming](core/operation-path-naming.md)
     1.  [Configuration](core/operation-path-naming.md#configuration)
     2.  [Create a Custom Operation Path Naming](core/operation-path-naming.md#create-a-custom-operation-path-resolver)
         1.  [Defining the Operation Path Naming](core/operation-path-naming.md#defining-the-operation-path-resolver)
         2.  [Registering the Service](core/operation-path-naming.md#registering-the-service)
         3.  [Configure it](core/operation-path-naming.md#configure-it)
-19. [Accept application/x-www-form-urlencoded Form Data](core/form-data.md)
-20. [FOSUserBundle Integration](core/fosuser-bundle.md)
+20. [Accept application/x-www-form-urlencoded Form Data](core/form-data.md)
+21. [FOSUserBundle Integration](core/fosuser-bundle.md)
     1.  [Installing the Bundle](core/fosuser-bundle.md#installing-the-bundle)
     2.  [Enabling the Bridge](core/fosuser-bundle.md#enabling-the-bridge)
     3.  [Creating a `User` Entity with Serialization Groups](core/fosuser-bundle.md#creating-a-user-entity-with-serialization-groups)
-21. [Adding a JWT authentication using LexikJWTAuthenticationBundle](core/jwt.md)
+22. [Adding a JWT authentication using LexikJWTAuthenticationBundle](core/jwt.md)
     1. [Testing with Swagger](core/jwt.md#testing-with-swagger)
     2. [Testing with Behat](core/jwt.md#testing-with-behat)
-22. [NelmioApiDocBundle integration](core/nelmio-api-doc.md)
-23. [AngularJS Integration](core/angularjs-integration.md)
+23. [NelmioApiDocBundle integration](core/nelmio-api-doc.md)
+24. [AngularJS Integration](core/angularjs-integration.md)
     1.  [Restangular](core/angularjs-integration.md#restangular)
     2.  [ng-admin](core/angularjs-integration.md#ng-admin)
-24. [Swagger Support](core/swagger.md)
+25. [Swagger Support](core/swagger.md)
     1. [Override Swagger documentation](core/swagger.md#override-swagger-documentation)
-25. [GraphQL Support](core/graphql.md)
+26. [GraphQL Support](core/graphql.md)
     1. [Overall View](core/graphql.md#overall-view)
     2. [Enabling GraphQL](core/graphql.md#enabling-graphql)
     3. [GraphiQL](core/graphql.md#graphiql)
-26. [The Serialization Process](core/serialization.md)
+27. [The Serialization Process](core/serialization.md)
     1. [Overall Process](core/serialization.md#overall-process)
     2. [Available Serializers](core/serialization.md#available-serializers)
     3. [Decorating a Serializer and Add Extra Data](core/serialization.md#decorating-a-serializer-and-add-extra-data)
-27. [Handling Data Transfer Objects (DTOs)](core/dto.md)
+28. [Handling Data Transfer Objects (DTOs)](core/dto.md)
 
 ## The Schema Generator Component: Generate Data Models from Open Vocabularies