Add strategies to extract debug information

Depending on the application mode, we may need extra debugging
information in the response body - which can definitely help us to solve
the issue more easily.

This provides the extension point and two default implementations:

 - `NoDebugInfo`: aimed for production mode, doesn't add any debug
   information
 - `NoTrace`: aimed for development mode, extracts all exception
   data but the trace - also for previous exceptions.

Author: lcobucci

src/DebugInfoStrategy.php

@@ -0,0 +1,14 @@
+<?php
+declare(strict_types=1);
+
+namespace Lcobucci\ErrorHandling;
+
+use Throwable;
+
+interface DebugInfoStrategy
+{
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function extractDebugInfo(Throwable $error): ?array;
+}

src/DebugInfoStrategy/NoDebugInfo.php

@@ -0,0 +1,18 @@
+<?php
+declare(strict_types=1);
+
+namespace Lcobucci\ErrorHandling\DebugInfoStrategy;
+
+use Lcobucci\ErrorHandling\DebugInfoStrategy;
+use Throwable;
+
+final class NoDebugInfo implements DebugInfoStrategy
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function extractDebugInfo(Throwable $error): ?array
+    {
+        return null;
+    }
+}

src/DebugInfoStrategy/NoTrace.php

@@ -0,0 +1,52 @@
+<?php
+declare(strict_types=1);
+
+namespace Lcobucci\ErrorHandling\DebugInfoStrategy;
+
+use Generator;
+use Lcobucci\ErrorHandling\DebugInfoStrategy;
+use Throwable;
+use function get_class;
+use function iterator_to_array;
+
+final class NoTrace implements DebugInfoStrategy
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function extractDebugInfo(Throwable $error): ?array
+    {
+        $debugInfo = $this->format($error);
+        $stack     = iterator_to_array($this->streamStack($error->getPrevious()), false);
+
+        if ($stack !== []) {
+            $debugInfo['stack'] = $stack;
+        }
+
+        return $debugInfo;
+    }
+
+    private function streamStack(?Throwable $previous): Generator
+    {
+        if ($previous === null) {
+            return;
+        }
+
+        yield $this->format($previous);
+        yield from $this->streamStack($previous->getPrevious());
+    }
+
+    /**
+     * @return array<string, string|int>
+     */
+    private function format(Throwable $error): array
+    {
+        return [
+            'class'   => get_class($error),
+            'code'    => $error->getCode(),
+            'message' => $error->getMessage(),
+            'file'    => $error->getFile(),
+            'line'    => $error->getLine(),
+        ];
+    }
+}

tests/DebugInfoStrategy/NoDebugInfoTest.php

@@ -0,0 +1,26 @@
+<?php
+declare(strict_types=1);
+
+namespace Lcobucci\ErrorHandling\Tests\DebugInfoStrategy;
+
+use Lcobucci\ErrorHandling\DebugInfoStrategy\NoDebugInfo;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+/**
+ * @coversDefaultClass \Lcobucci\ErrorHandling\DebugInfoStrategy\NoDebugInfo
+ */
+final class NoDebugInfoTest extends TestCase
+{
+    /**
+     * @test
+     *
+     * @covers ::extractDebugInfo
+     */
+    public function extractDebugInfoShouldAlwaysReturnNull(): void
+    {
+        $strategy = new NoDebugInfo();
+
+        self::assertNull($strategy->extractDebugInfo(new RuntimeException()));
+    }
+}

tests/DebugInfoStrategy/NoTraceTest.php

@@ -0,0 +1,88 @@
+<?php
+declare(strict_types=1);
+
+namespace Lcobucci\ErrorHandling\Tests\DebugInfoStrategy;
+
+use InvalidArgumentException;
+use Lcobucci\ErrorHandling\DebugInfoStrategy\NoTrace;
+use LogicException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+/**
+ * @coversDefaultClass \Lcobucci\ErrorHandling\DebugInfoStrategy\NoTrace
+ */
+final class NoTraceTest extends TestCase
+{
+    /**
+     * @test
+     *
+     * @covers ::extractDebugInfo
+     * @covers ::format
+     * @covers ::streamStack
+     */
+    public function extractDebugInfoShouldConvertExceptionInfoWithoutTheTrace(): void
+    {
+        $strategy = new NoTrace();
+
+        self::assertSame(
+            [
+                'class'   => RuntimeException::class,
+                'code'    => 11,
+                'message' => 'Testing',
+                'file'    => __FILE__,
+                'line'    => __LINE__ + 2,
+            ],
+            $strategy->extractDebugInfo(new RuntimeException('Testing', 11))
+        );
+    }
+
+    /**
+     * @test
+     *
+     * @covers ::extractDebugInfo
+     * @covers ::format
+     * @covers ::streamStack
+     */
+    public function extractDebugInfoShouldAlsoReturnPreviousExceptions(): void
+    {
+        $strategy = new NoTrace();
+
+        self::assertSame(
+            [
+                'class'   => RuntimeException::class,
+                'code'    => 11,
+                'message' => 'Testing',
+                'file'    => __FILE__,
+                'line'    => __LINE__ + 19,
+                'stack'   => [
+                    [
+                        'class'   => InvalidArgumentException::class,
+                        'code'    => 25,
+                        'message' => 'Oh no!',
+                        'file'    => __FILE__,
+                        'line'    => __LINE__ + 15,
+                    ],
+                    [
+                        'class'   => LogicException::class,
+                        'code'    => 0,
+                        'message' => 'Bummer',
+                        'file'    => __FILE__,
+                        'line'    => __LINE__ + 11,
+                    ],
+                ],
+            ],
+            $strategy->extractDebugInfo(
+                new RuntimeException(
+                    'Testing',
+                    11,
+                    new InvalidArgumentException(
+                        'Oh no!',
+                        25,
+                        new LogicException('Bummer')
+                    )
+                )
+            )
+        );
+    }
+}