prototype-better-error-handling

Author: dominikzogg

README.md

@@ -35,7 +35,7 @@ Heavily inspired by the well-known TypeScript library [zod](https://github.com/c
 Through [Composer](http://getcomposer.org) as [chubbyphp/chubbyphp-parsing][1].
 
 ```sh
-composer require chubbyphp/chubbyphp-parsing "^1.4"
+composer require chubbyphp/chubbyphp-parsing "^2.0"
 ```
 
 ## Usage
@@ -51,7 +51,7 @@ $schema->preParse(static fn ($input) => $input);
 $schema->postParse(static fn (string $output) => $output);
 $schema->parse('test');
 $schema->safeParse('test');
-$schema->catch(static fn (string $output, ParserErrorException $e) => $output);
+$schema->catch(static fn (string $output, ErrorsException $e) => $output);
 ```
 
 ### array

composer.json

@@ -50,7 +50,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.4-dev"
+            "dev-master": "2.0-dev"
         }
     },
     "scripts": {

phpstan.neon

@@ -1,8 +1,5 @@
 parameters:
     ignoreErrors:
-        -
-            message: '/type specified in iterable type array/'
-            path: %currentWorkingDirectory%/src/ParserErrorException.php
         -
             message: '/Instanceof between Chubbyphp\\Parsing\\Schema\\ObjectSchemaInterface and Chubbyphp\\Parsing\\Schema\\ObjectSchemaInterface will always evaluate to true./'
             path: %currentWorkingDirectory%/src/Schema/DiscriminatedUnionSchema.php

src/Error.php

@@ -4,12 +4,15 @@
 
 namespace Chubbyphp\Parsing;
 
-final class Error
+/**
+ * @phpstan-type ErrorAsJson array{code: string, template: string, variables: array<string, mixed>}
+ */
+final class Error implements \JsonSerializable
 {
     /**
      * @param array<string, mixed> $variables
      */
-    public function __construct(public string $code, public string $template, public array $variables) {}
+    public function __construct(public readonly string $code, public readonly string $template, public readonly array $variables) {}
 
     public function __toString()
     {
@@ -25,4 +28,12 @@ public function __toString()
 
         return $message;
     }
+
+    /**
+     * @return ErrorAsJson
+     */
+    public function jsonSerialize(): array
+    {
+        return ['code' => $this->code, 'template' => $this->template, 'variables' => json_decode(json_encode($this->variables), true)];
+    }
 }

src/Errors.php

@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Chubbyphp\Parsing;
+
+/**
+ * @phpstan-type ErrorWithPath array{path: string, error: Error}
+ * @phpstan-type ErrorsWithPath array<ErrorWithPath>
+ * @phpstan-type ErrorAsJson array{code: string, template: string, variables: array<string, mixed>}
+ * @phpstan-type ErrorWithPathJson array{path: string, error: ErrorAsJson}
+ * @phpstan-type ErrorsWithPathJson array<ErrorWithPathJson>
+ * @phpstan-type ApiProblem array{name: string, reason: string, details: non-empty-array<string, mixed>}
+ */
+final class Errors implements \JsonSerializable
+{
+    /**
+     * @var ErrorsWithPath
+     */
+    private array $errorsWithPath = [];
+
+    public function __toString()
+    {
+        return implode(PHP_EOL, array_map(static fn ($error) => $error['path'].': '.(string) $error['error'], $this->errorsWithPath));
+    }
+
+    public function addErrors(self $errors, string $path = ''): self
+    {
+        foreach ($errors->errorsWithPath as $errorWithPath) {
+            $this->errorsWithPath[] = ['path' => $this->mergePath($path, $errorWithPath['path']), 'error' => $errorWithPath['error']];
+        }
+
+        return $this;
+    }
+
+    public function addError(Error $error, string $path = ''): self
+    {
+        $this->errorsWithPath[] = ['path' => $path, 'error' => $error];
+
+        return $this;
+    }
+
+    public function hasErrors(): bool
+    {
+        return 0 !== \count($this->errorsWithPath);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toTree(): array
+    {
+        // @var array<string, mixed> $tree
+        return array_reduce(
+            $this->errorsWithPath,
+            static function (array $tree, $errorWithPath): array {
+                $pathParts = explode('.', $errorWithPath['path']);
+
+                $current = &$tree;
+                $lastIndex = \count($pathParts) - 1;
+
+                foreach ($pathParts as $i => $pathPart) {
+                    if ($i < $lastIndex) {
+                        $current[$pathPart] ??= [];
+                        $current = &$current[$pathPart];
+
+                        continue;
+                    }
+
+                    $current[$pathPart] = array_merge($current[$pathPart] ?? [], [(string) $errorWithPath['error']]);
+                }
+
+                return $tree;
+            },
+            []
+        );
+    }
+
+    /**
+     * @return array<ApiProblem>
+     */
+    public function toApiProblems(): array
+    {
+        return array_map(
+            fn ($errorWithPath) => [
+                'name' => $this->pathToName($errorWithPath['path']),
+                'reason' => (string) $errorWithPath['error'],
+                'details' => [
+                    '_template' => $errorWithPath['error']->template,
+                    ...$errorWithPath['error']->variables,
+                ],
+            ],
+            $this->errorsWithPath
+        );
+    }
+
+    /**
+     * @return ErrorsWithPathJson
+     */
+    public function jsonSerialize(): array
+    {
+        return array_map(static fn ($errorWithPath) => [
+            'path' => $errorWithPath['path'],
+            'error' => $errorWithPath['error']->jsonSerialize(),
+        ], $this->errorsWithPath);
+    }
+
+    private function mergePath(string $path, string $existingPath): string
+    {
+        return implode('.', array_filter([$path, $existingPath], static fn ($part) => '' !== $part));
+    }
+
+    private function pathToName(string $path): string
+    {
+        $pathParts = explode('.', $path);
+
+        return implode('', array_map(
+            static fn (string $pathPart, $i) => 0 === $i ? $pathPart : '['.$pathPart.']',
+            $pathParts,
+            array_keys($pathParts)
+        ));
+    }
+}

src/ErrorsException.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Chubbyphp\Parsing;
+
+final class ErrorsException extends \RuntimeException
+{
+    private function __construct(public readonly Errors $errors)
+    {
+        $this->message = (string) $errors;
+    }
+
+    public static function fromErrors(Errors $errors): self
+    {
+        return new self($errors);
+    }
+
+    public static function fromError(Error $error): self
+    {
+        return new self(new Errors()->addError($error));
+    }
+}

src/ParserErrorException.php

@@ -8,7 +8,7 @@ final class Result
 {
     public bool $success;
 
-    public function __construct(public mixed $data, public ?ParserErrorException $exception)
+    public function __construct(public mixed $data, public ?ErrorsException $exception)
     {
         $this->success = null === $exception;
     }