Merge pull request #2 from lcobucci/improve-documentation

Improve documentation

README.md

@@ -5,7 +5,7 @@
 [![Unstable Version](https://img.shields.io/packagist/vpre/lcobucci/error-handling-middleware.svg?style=flat-square)](https://packagist.org/packages/lcobucci/error-handling-middleware)
 
 ![Branch master](https://img.shields.io/badge/branch-master-brightgreen.svg?style=flat-square)
-[![Build Status](https://img.shields.io/travis/lcobucci/error-handling-middleware/master.svg?style=flat-square)](http://travis-ci.org/#!/lcobucci/error-handling-middleware)
+[![Build Status](https://img.shields.io/travis/lcobucci/error-handling-middleware/master.svg?style=flat-square)](http://travis-ci.org/lcobucci/error-handling-middleware)
 [![Scrutinizer Code Quality](https://img.shields.io/scrutinizer/g/lcobucci/error-handling-middleware/master.svg?style=flat-square)](https://scrutinizer-ci.com/g/lcobucci/error-handling-middleware/?branch=master)
 [![Code Coverage](https://img.shields.io/scrutinizer/coverage/g/lcobucci/error-handling-middleware/master.svg?style=flat-square)](https://scrutinizer-ci.com/g/lcobucci/error-handling-middleware/?branch=master)
 
@@ -22,16 +22,183 @@ flexibility to solve this problem.
 
 ## Installation
 
-This package is available on [Packagist](http://packagist.org/packages/lcobucci/error-handling-middleware),
-and we recommend you to install it using [Composer](http://getcomposer.org):
+This package is available on [Packagist](https://packagist.org/packages/lcobucci/error-handling-middleware),
+and we recommend you to install it using [Composer](https://getcomposer.org):
 
 ```shell
 composer require lcobucci/error-handling-middleware
 ```
 
 ## Usage
 
-TDB
+In order to us this package you must add the middleware to your pipeline, configuring
+the desired behaviour (debug info strategy and status code extraction strategy).
+
+Once this is set you'll be able to have your errors/exceptions converted into the
+correct HTTP responses.
+
+### Middleware position
+
+This package provides two middleware for handling errors: error logging and error
+conversion.
+
+They are designed to be used in the very beginning of the HTTP middleware pipeline,
+just after the [content negotiation](https://github.com/lcobucci/content-negotiation-middleware) one:
+
+```php
+<?php
+use Lcobucci\ContentNegotiation\ContentTypeMiddleware;
+use Lcobucci\ErrorHandling\ErrorConversionMiddleware;
+use Lcobucci\ErrorHandling\ErrorLoggingMiddleware;
+
+// In a Zend Expressive application, it would look like this:
+$application->pipe(ContentTypeMiddleware::fromRecommendedSettings( /* ... */ )); // Very first middleware
+$application->pipe(new ErrorConversionMiddleware( /* ... */ ));
+$application->pipe(new ErrorLoggingMiddleware( /* ... */ ));
+
+// all other middleware.
+```
+
+With that we'll be able to perform the logging and conversion in the correct order,
+delegating the content negotiation and formatting to `ContentTypeMiddleware` - using
+the configured formatters.
+
+#### Important
+
+The `ErrorConversionMiddleware` uses an `UnformattedResponse` to let the
+`ContentTypeMiddleware` perform the formatting. Make sure you have configured
+formatters for the MIME types `application/problem+json` and/or
+`application/problem+xml`.
+
+It also makes the error/exception available in the `error` attribute of the response,
+so you may access it (if needed) by using another middleware between
+`ErrorConversionMiddleware` and `ContentTypeMiddleware`.
+
+### Configuring the conversion middleware behaviour
+
+There're two extension points that you can use for that: debug info strategy and
+status code extraction strategy.
+
+You can also configure the response body attributes by implementing certain interfaces
+in your exceptions.
+
+#### Debug info strategy
+
+This defines how the `_debug` property should be generated in the response body.
+We provide two default implementations - one designed for production mode and the
+other for development mode.
+
+To configure this you must pass the desired implementation (or a customised one) as
+the second argument of the `ErrorConversionMiddleware` constructor.
+
+To provide your own implementation you need to create a class that implements the
+`DebugInfoStrategy` interface.
+
+#### Status code extraction strategy
+
+This defines how the translation from error/exception to HTTP status code should
+be done. We provide a single default implementation for that, which is based on
+class maps.
+
+To configure this you must pass the desired implementation (or a customised one) as
+the third argument of the `ErrorConversionMiddleware` constructor.
+
+To provide your own implementation you need to create a class that implements the
+`StatusCodeExtractionStrategy` interface.
+
+##### Default class map
+
+The default map uses the marker interfaces in this packages to perform such translation.
+If the error/exception doesn't implement any of the marker interfaces, the error/exception
+code will be used (when it's different than zero), or fallback to the status code
+500 (Internal Server Error).
+
+The default map is:
+
+* `Lcobucci\ErrorHandling\Problem\InvalidRequest` -> `400`
+* `Lcobucci\ErrorHandling\Problem\AuthorizationRequired` -> `401`
+* `Lcobucci\ErrorHandling\Problem\Forbidden` -> `403`
+* `Lcobucci\ErrorHandling\Problem\ResourceNotFound` -> `404`
+* `Lcobucci\ErrorHandling\Problem\Conflict` -> `409`
+* `Lcobucci\ErrorHandling\Problem\ResourceNoLongerAvailable` -> `410`
+* `Lcobucci\ErrorHandling\Problem\UnprocessableRequest` -> `422`
+* `Lcobucci\ErrorHandling\Problem\ServiceUnavailable`-> `503`
+
+This allows us to create our own exceptions that are automatically converted to the
+correct status code:
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace My\Fancy\App\UserManagement;
+
+use Lcobucci\ErrorHandling\Problem\ResourceNotFound;
+use RuntimeException;
+
+final class UserNotFound extends RuntimeException implements ResourceNotFound
+{
+}
+```
+
+**Important**: you SHOULD NOT implement more than one of the marker interfaces,
+otherwise you may have unexpected results.
+
+#### Customising the response body properties
+
+With this library, you may modify the `type` and `title` properties of the generated
+response and also append new members to it.
+
+That's done by implementing the `Typed`, `Titled`, and/or `Detailed` interfaces -
+you don't necessarily need to implement all of them, only the ones you want.
+
+The example below shows how to represent one of the samples in the
+[RFC 7807](https://tools.ietf.org/html/rfc7807#section-3):
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace My\Fancy\App\UserManagement;
+
+use Lcobucci\ErrorHandling\Problem\Forbidden;
+use Lcobucci\ErrorHandling\Problem\Typed;
+use Lcobucci\ErrorHandling\Problem\Titled;
+use Lcobucci\ErrorHandling\Problem\Detailed;
+use RuntimeException;
+use function sprintf;
+
+final class InsufficientCredit extends RuntimeException implements Forbidden, Typed, Titled, Detailed
+{
+    private $currentBalance;
+
+    public static function forPurchase(int $currentBalance, int $cost): self
+    {
+        $exception = new self(sprintf('Your current balance is %d, but that costs %d.', $currentBalance, $cost));
+        $exception->currentBalance = $currentBalance;
+
+        return $exception;
+    }
+
+    public function getTypeUri(): string
+    {
+        return 'https://example.com/probs/out-of-credit';
+    }
+
+    public function getTitle(): string
+    {
+        return 'You do not have enough credit.';
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getExtraDetails(): array
+    {
+        return ['balance' => $this->currentBalance]; // you might add "instance" and "accounts" too :)
+    }
+}
+```
 
 ## License
 

src/DebugInfoStrategy.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Defines how the debug information should be extracted from an error/exception
+ */
 interface DebugInfoStrategy
 {
     /**

src/Problem/AuthorizationRequired.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to missing auth information (credentials or valid access token)
+ */
 interface AuthorizationRequired extends Throwable
 {
 }

src/Problem/Conflict.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to resource conflicts (version mismatch or duplicated data)
+ */
 interface Conflict extends Throwable
 {
 }

src/Problem/Detailed.php

@@ -5,6 +5,11 @@
 
 use Throwable;
 
+/**
+ * Provides extension members to the problem details
+ *
+ * @see https://tools.ietf.org/html/rfc7807#section-3.2
+ */
 interface Detailed extends Throwable
 {
     /**

src/Problem/Forbidden.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to forbidden operations (lack of permission)
+ */
 interface Forbidden extends Throwable
 {
 }

src/Problem/InvalidRequest.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to malformed requests (syntax issues)
+ */
 interface InvalidRequest extends Throwable
 {
 }

src/Problem/ResourceNoLongerAvailable.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to removed resource (removed/archived items)
+ */
 interface ResourceNoLongerAvailable extends Throwable
 {
 }

src/Problem/ResourceNotFound.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to non-existing resources
+ */
 interface ResourceNotFound extends Throwable
 {
 }

src/Problem/ServiceUnavailable.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to availability issues (maintenance or dependency issues)
+ */
 interface ServiceUnavailable extends Throwable
 {
 }

src/Problem/Titled.php

@@ -5,6 +5,13 @@
 
 use Throwable;
 
+/**
+ * Provides a custom (human-readable) summary of the problem
+ *
+ * The provided title SHOULD NOT vary from occurrence to occurrence.
+ *
+ * @see https://tools.ietf.org/html/rfc7807#section-3.1
+ */
 interface Titled extends Throwable
 {
     public function getTitle(): string;

src/Problem/Typed.php

@@ -5,6 +5,11 @@
 
 use Throwable;
 
+/**
+ * Provides a custom URI for the documentation of the problem
+ *
+ * @see https://tools.ietf.org/html/rfc7807#section-3.1
+ */
 interface Typed extends Throwable
 {
     public function getTypeUri(): string;

src/Problem/UnprocessableRequest.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Marker interface to be used in exceptions related to syntactically correct but semantically invalid requests
+ */
 interface UnprocessableRequest extends Throwable
 {
 }

src/StatusCodeExtractionStrategy.php

@@ -5,6 +5,9 @@
 
 use Throwable;
 
+/**
+ * Defines how the translation of errors/exceptions into HTTP status codes should happen
+ */
 interface StatusCodeExtractionStrategy
 {
     public function extractStatusCode(Throwable $error): int;