Merging develop to master in preparation for 1.1.0 release.

Author: weierophinney

CHANGELOG.md

@@ -4,11 +4,11 @@ All notable changes to this project will be documented in this file, in reverse
 
 Versions 0.3.0 and prior were released as "weierophinney/problem-details".
 
-## 1.0.3 - TBD
+## 1.1.0 - 2019-12-30
 
 ### Added
 
-- Nothing.
+- [#51](https://github.com/zendframework/zend-problem-details/pull/51) adds a new `problem-details.default_types_map` config option, which can be used to define custom `type` values based on status codes.
 
 ### Changed
 

composer.json

@@ -49,8 +49,8 @@
             "config-provider": "Zend\\ProblemDetails\\ConfigProvider"
         },
         "branch-alias": {
-            "dev-master": "1.0.x-dev",
-            "dev-develop": "1.1.x-dev"
+            "dev-master": "1.1.x-dev",
+            "dev-develop": "1.2.x-dev"
         }
     },
     "scripts": {

composer.lock

@@ -0,0 +1,52 @@
+# Default Types
+
+- **Since 1.1.0.**
+
+When you raise your own exceptions implementing `Zend\ProblemDetails\Exception\ProblemDetailsExceptionInterface` 
+you will always be in control of all the properties returned as part of the
+response payload, including the `status`, `type`, `title`, `detail`, etc.
+items.
+
+However, there are some use cases in which this library will have to infer some
+of those values.
+
+The main situations in which this can happen are:
+
+- When an exception not implementing `ProblemDetailsExceptionInterface` is
+  captured by the `ProblemDetailsMiddleware`.
+- When the `ProblemDetailsNotFoundHandler` is executed.
+
+In these two cases, the `title` and `type` properties will be inferred from the
+status code, which will usually be `500` in the first case and `404` in the
+second one.
+
+> To be more precise, the `ProblemDetailsMiddleware` will use the exception's
+> error code when `debug` is `true`, and `500` otherwise.
+
+Because of this, in any of those cases, you will end up with values like
+`https://httpstatus.es/404` or `https://httpstatus.es/500` for the `type`
+property.
+
+## Configuring custom default types
+
+Since the `type` property will usually be used by API consumers to uniquely
+identify an error, you might want to be able to provide your own custom values
+for the `type` property.
+
+In order to do that, this library lets you configure the default `type` value to
+be used for every status code when some of the cases listed above happens.
+
+```php
+return [
+    'problem-details' => [
+        'default_types_map' => [
+            404 => 'https://example.com/problem-details/error/not-found',
+            500 => 'https://example.com/problem-details/error/internal-server-error',
+        ],
+    ],
+];
+```
+
+If this configuration is found, it will be consumed by the
+[ProblemDetailsResponseFactoryFactory](response.md#problemdetailsresponsefactoryfactory)
+and your custom values will be used when the `type` was not explicitly provided.

docs/book/default-types.md

@@ -146,6 +146,11 @@ This package also provides a factory for generating the
     - If the service contains a `problem-details` key with an array value
       containing a `json_flags` key, and that value is an integer, that value is
       provided as the `$jsonFlags` parameter.
+    - If the service contains a `problem-details` key with an array value
+      containing a `default_types_map` key, and that value is an array, that
+      value is provided as the `$defaultTypesMap` parameter; see the
+      [default types documentation](default-types.md) for details on defining
+      this map. (Since 1.1.0.)
 
 If any of the above config values are not present, a `null` value will be
 passed, allowing the default value to be used.

docs/book/response.md

@@ -9,6 +9,7 @@ pages:
         - "Exceptions": exception.md
         - "Error Handling Middleware": middleware.md
         - "Not Found Handler": not-found-handler.md
+        - "Default Types": default-types.md
 site_name: zend-problem-details
 site_description: 'PSR-7 Problem Details for HTTP API responses and middleware'
 repo_url: 'https://github.com/zendframework/zend-problem-details'

mkdocs.yml

@@ -204,12 +204,22 @@ class ProblemDetailsResponseFactory
      */
     private $defaultDetailMessage;
 
+    /**
+     * A map used to infer the "type" property based on the status code.
+     *
+     * Defaults to an empty map.
+     *
+     * @var array
+     */
+    private $defaultTypesMap;
+
     public function __construct(
         callable $responseFactory,
         bool $isDebug = self::EXCLUDE_THROWABLE_DETAILS,
         int $jsonFlags = null,
         bool $exceptionDetailsInResponse = false,
-        string $defaultDetailMessage = self::DEFAULT_DETAIL_MESSAGE
+        string $defaultDetailMessage = self::DEFAULT_DETAIL_MESSAGE,
+        array $defaultTypesMap = []
     ) {
         // Ensures type safety of the composed factory
         $this->responseFactory = function () use ($responseFactory) : ResponseInterface {
@@ -228,6 +238,7 @@ public function __construct(
         $this->jsonFlags = $jsonFlags;
         $this->exceptionDetailsInResponse = $exceptionDetailsInResponse;
         $this->defaultDetailMessage = $defaultDetailMessage;
+        $this->defaultTypesMap = $defaultTypesMap;
     }
 
     public function createResponse(
@@ -392,7 +403,7 @@ private function createTitleFromStatus(int $status) : string
 
     private function createTypeFromStatus(int $status) : string
     {
-        return sprintf('https://httpstatus.es/%s', $status);
+        return $this->defaultTypesMap[$status] ?? sprintf('https://httpstatus.es/%s', $status);
     }
 
     private function createThrowableDetail(Throwable $e) : array

src/ProblemDetailsResponseFactory.php

@@ -21,12 +21,15 @@ public function __invoke(ContainerInterface $container) : ProblemDetailsResponse
 
         $problemDetailsConfig = $config['problem-details'] ?? [];
         $jsonFlags = $problemDetailsConfig['json_flags'] ?? null;
+        $defaultTypesMap = $problemDetailsConfig['default_types_map'] ?? [];
 
         return new ProblemDetailsResponseFactory(
             $container->get(ResponseInterface::class),
             $includeThrowableDetail,
             $jsonFlags,
-            $includeThrowableDetail
+            $includeThrowableDetail,
+            ProblemDetailsResponseFactory::DEFAULT_DETAIL_MESSAGE,
+            $defaultTypesMap
         );
     }
 }

src/ProblemDetailsResponseFactoryFactory.php

@@ -139,4 +139,25 @@ public function testUsesJsonFlagsSettingFromConfigWhenPresent() : void
         $this->assertInstanceOf(ProblemDetailsResponseFactory::class, $factory);
         $this->assertAttributeSame(JSON_PRETTY_PRINT, 'jsonFlags', $factory);
     }
+
+    public function testUsesDefaultTypesSettingFromConfigWhenPresent() : void
+    {
+        $expectedDefaultTypes = [
+            404 => 'https://example.com/problem-details/error/not-found',
+        ];
+
+        $this->container->has('config')->willReturn(true);
+        $this->container->get('config')->willReturn(
+            ['problem-details' => ['default_types_map' => $expectedDefaultTypes]]
+        );
+
+        $this->container->get(ResponseInterface::class)->willReturn(function () {
+        });
+
+        $factoryFactory = new ProblemDetailsResponseFactoryFactory();
+        $factory = $factoryFactory($this->container->reveal());
+
+        $this->assertInstanceOf(ProblemDetailsResponseFactory::class, $factory);
+        $this->assertAttributeSame($expectedDefaultTypes, 'defaultTypesMap', $factory);
+    }
 }

test/ProblemDetailsResponseFactoryFactoryTest.php

@@ -24,6 +24,7 @@
 use function array_keys;
 use function fclose;
 use function fopen;
+use function json_decode;
 use function stripos;
 
 class ProblemDetailsResponseFactoryTest extends TestCase
@@ -475,4 +476,55 @@ function (array $payload) {
 
         $this->assertSame($this->response->reveal(), $response);
     }
+
+    public function provideMappedStatuses() : array
+    {
+        $defaultTypesMap = [
+            404 => 'https://example.com/problem-details/error/not-found',
+            500 => 'https://example.com/problem-details/error/internal-server-error',
+        ];
+
+        return [
+            [$defaultTypesMap, 404, 'https://example.com/problem-details/error/not-found'],
+            [$defaultTypesMap, 500, 'https://example.com/problem-details/error/internal-server-error'],
+            [$defaultTypesMap, 400, 'https://httpstatus.es/400'],
+            [[], 500, 'https://httpstatus.es/500'],
+        ];
+    }
+
+    /**
+     * @dataProvider provideMappedStatuses
+     */
+    public function testTypeIsInferredFromDefaultTypesMap(array $map, int $status, string $expectedType) : void
+    {
+        $this->request->getHeaderLine('Accept')->willReturn('application/json');
+
+        $stream = $this->prophesize(StreamInterface::class);
+        $writeStream = $stream->write(Argument::that(function (string $body) use ($expectedType) {
+            $payload = json_decode($body, true);
+            Assert::assertEquals($expectedType, $payload['type']);
+
+            return $body;
+        }));
+
+        $this->response->getBody()->will([$stream, 'reveal']);
+        $withStatus = $this->response->withStatus($status)->will([$this->response, 'reveal']);
+        $this->response->withHeader('Content-Type', 'application/problem+json')->will([$this->response, 'reveal']);
+
+        $factory = new ProblemDetailsResponseFactory(
+            function () {
+                return $this->response->reveal();
+            },
+            false,
+            null,
+            false,
+            '',
+            $map
+        );
+
+        $factory->createResponse($this->request->reveal(), $status, 'detail');
+
+        $writeStream->shouldHaveBeenCalled();
+        $withStatus->shouldHaveBeenCalled();
+    }
 }