Merge pull request #406 from GregoireHebert/GregoireHebert-exception-rebased

Errors to Exception

Author: dunglas

core/errors.md

@@ -0,0 +1,96 @@
+# Errors Handling
+
+API Platform comes with a powerful error system. It handles excepted (such as faulty JSON documents sent by the
+client or validation errors) as well as unexpected errors (PHP exceptions and errors).
+API Platform automatically sends the appropriate HTTP status code to the client: `400` for expected errors, `500` for
+unexpected ones. It also provides a description of the error in [the Hydra error format](http://www.hydra-cg.com/spec/latest/core/#description-of-http-status-codes-and-errors)
+or in the format described in the [RFC 7807](https://tools.ietf.org/html/rfc7807), depending of the format selected during the [content negotiation](content-negotiation.md).
+
+## Converting PHP Exceptions to HTTP Errors
+
+The framework also allows to configure the HTTP status code sent to the clients when custom exceptions are thrown.
+
+In the following example, we throw a domain exception from the business layer of the application and
+configure API Platform to convert it to a `404 Not Found` error:
+
+```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
+{
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            KernelEvents::REQUEST => ['checkProductAvailability', EventPriorities::POST_DESERIALIZE],
+        ];
+    }
+
+    public function checkProductAvailability(GetResponseForControllerResultEvent $event): void
+    {
+        $product = $event->getControllerResult();
+        if (!$product instanceof Product || !$event->getRequest()->isMethodSafe(false)) {
+            return;
+        }
+
+        if (!$product->isPubliclyAvailable()) {
+            // Using internal codes for a better understanding of what's going on
+            throw new ProductNotFoundException(sprintf('The product "%s" does not exist.', $product->getId()));
+        }
+    }
+}
+```
+
+If you use the standard distribution of API Platform, this event listener will be automatically registered. If you use a
+custom installation, [learn how to register listeners](events.md).
+
+Then, configure the framework to catch `AppBundle\Exception\ProductNotFoundException` exceptions and convert them in `404`
+errors:
+
+```yaml
+# config/packages/api_platform.yaml
+api_platform:
+    # ...
+    exception_to_status:
+        # The 2 following handlers are registered by default, keep those lines to prevent unexpected side effects
+        Symfony\Component\Serializer\Exception\ExceptionInterface: 400 # Use a raw status code (recommended)
+        ApiPlatform\Core\Exception\InvalidArgumentException: 'HTTP_BAD_REQUEST' # Or a `Symfony\Component\HttpFoundation\Response`'s constant
+
+        AppBundle\Exception\ProductNotFoundException: 404 # Here is the handler for our custom exception
+```
+
+Any type of `Exception` can be thrown, API Platform will convert it to a Symfony's `HttpException`. The framework also takes
+care of serializing the error description according to the request format. For instance, if the API should respond in JSON-LD,
+the error will be returned in this format as well:
+
+`GET /products/1234`
+
+```json
+{
+  "@context": "/contexts/Error",
+  "@type": "Error",
+  "hydra:title": "An error occurred",
+  "hydra:description": "The product \"1234\" does not exist."
+}
+```

core/validation.md

@@ -1,15 +1,134 @@
 # Validation
 
-API Platform Core uses the [Symfony Validator component](http://symfony.com/doc/current/book/validation.html) to validate
-entities.
+API Platform take care of validating data sent to the API by the client (usually user data entered through forms).
+By default, the framework relies on [the powerful Symfony Validator Component](http://symfony.com/doc/current/validation.html)
+for this task, but you can replace it by your preferred validation library such as [the PHP filter extension](http://php.net/manual/en/intro.filter.php)
+if you want to.
 
-Without specific configuration, it uses the default validation group, but this behavior is customizable.
+## Validating Submitted Data
+
+Validating submitted data is simple as adding [Symfony's builtin constraints](http://symfony.com/doc/current/reference/constraints.html)
+or [custom constraints](http://symfony.com/doc/current/validation/custom_constraint.html) directly in classes marked with
+the `@ApiResource` annotation:
+
+```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; // Symfony's builtin constraints
+use AppBundle\Validator\Constraints\MinimalProperties; // A custom constraint
+
+/**
+ * A product.
+ *
+ * @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
+     *
+     * @Assert\NotBlank
+     * @ORM\Column
+     */
+    private name;
+
+    /**
+     * @var string[] Describe the product
+     *
+     * @MinimalProperties
+     * @ORM\Column(type="json")
+     */
+    private $properties;
+
+    // Getters and setters...
+}
+```
+
+Here is a custom constraint and the related validator:
+
+```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")';
+}
+```
+
+```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): void
+    {
+        if (!array_diff(['description', 'price'], $value)) {
+            $this->context->buildViolation($constraint->message)->addViolation();
+        }
+    }
+}
+```
+
+If the data submitted by the client is invalid, the HTTP status code will be set to `400 Bad Request` and the response's
+body will contain the list of violations serialized in a format compliant with the requested one. For instance, a validation
+error will look like the following if the requested format is JSON-LD (the default):
+
+```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\")"
+    }
+  ]
+}
+```
+
+Take a look at the [Errors Handling guide](errors.md) to learn how API Platform converts PHP exceptions like validation
+errors to HTTP errors.
 
 ## Using Validation Groups
 
-Built-in actions are able to leverage Symfony's [validation groups](http://symfony.com/doc/current/book/validation.html#validation-groups).
+Without specific configuration, the default validation group is always used, but this behavior is customizable: the framework
+is able to leverage Symfony's [validation groups](http://symfony.com/doc/current/book/validation.html#validation-groups).
 
-You can customize them by editing the resource configuration and add the groups you want to use when the validation occurs:
+You can configure the groups you want to use when the validation occurs directly through the `ApiResource` annotation:
 
 ```php
 <?php
@@ -20,6 +139,7 @@ use Symfony\Component\Validator\Constraints as Assert;
 
 /**
  * @ApiResource(attributes={"validation_groups"={"a", "b"}})
+ * ...
  */
 class Book
 {

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