Provide minimal spec-compliant error format

UPGRADE.md

@@ -1,3 +1,56 @@
+## v14.x.x > v15.x.x
+
+### BREAKING: Removed error extension field `category`
+
+The formatting of errors that implement the `ClientAware` interface no longer
+contains the key `category`. This includes both built-in and user-defined errors.
+
+```php
+throw new \GraphQL\Error\Error('msg');
+```
+
+Formatting before the change:
+```php
+'errors' => [
+    [
+        'message' => 'msg',
+        'extensions' => [
+            'category' => 'graphql',
+        ],
+    ],
+]
+```
+After the change:
+```php
+'errors' => [
+    [
+        'message' => 'msg',
+    ],
+]
+```
+
+The method `ClientAware::getCategory()` was removed, you may also remove it from your implementations:
+
+```diff
+use GraphQL\Error\ClientAware;
+
+class MyException extends \Exception implements ClientAware
+{
+    public function isClientSafe(): bool
+    {
+        return true;
+    }
+
+-   public function getCategory(): string
+-   {
+-       return 'my-category';
+-   }
+}
+```
+
+You can always switch to [custom error formatting](https://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting)
+to revert to the old format.
+
 ## v0.13.x > v14.x.x
 
 ### BREAKING: Strict coercion of scalar types (#278)

composer.json

@@ -19,14 +19,14 @@
     "doctrine/coding-standard": "^8.2",
     "ergebnis/composer-normalize": "^2.13",
     "nyholm/psr7": "^1.2",
-    "phpbench/phpbench": "1.0.0-beta1",
-    "phpstan/extension-installer": "^1.0",
-    "phpstan/phpstan": "0.12.82",
-    "phpstan/phpstan-phpunit": "0.12.18",
-    "phpstan/phpstan-strict-rules": "0.12.9",
+    "phpbench/phpbench": "^1",
+    "phpstan/extension-installer": "^1",
+    "phpstan/phpstan": "0.12.93",
+    "phpstan/phpstan-phpunit": "0.12.21",
+    "phpstan/phpstan-strict-rules": "0.12.10",
     "phpunit/phpunit": "^9.5",
-    "psr/http-message": "^1.0",
-    "react/promise": "2.*"
+    "psr/http-message": "^1",
+    "react/promise": "^2"
   },
   "suggest": {
     "psr/http-message": "To use standard GraphQL server",

docs/error-handling.md

@@ -36,16 +36,16 @@ By default, each error entry is converted to an associative array with following
 [
     'message' => 'Error message',
     'extensions' => [
-        'category' => 'graphql'
+        'key' => 'value',
     ],
     'locations' => [
-        ['line' => 1, 'column' => 2]
+        ['line' => 1, 'column' => 2],
     ],
     'path' => [
         'listField',
         0,
-        'fieldWithException'
-    ]
+        'fieldWithException',
+    ],
 ];
 ```
 
@@ -73,15 +73,10 @@ use GraphQL\Error\ClientAware;
 
 class MySafeException extends \Exception implements ClientAware
 {
-    public function isClientSafe()
+    public function isClientSafe(): bool
     {
         return true;
     }
-
-    public function getCategory()
-    {
-        return 'businessLogic';
-    }
 }
 ```
 
@@ -91,16 +86,13 @@ When such exception is thrown it will be reported with a full error message:
 <?php
 [
     'message' => 'My reported error',
-    'extensions' => [
-        'category' => 'businessLogic'
-    ],
     'locations' => [
-        ['line' => 10, 'column' => 2]
+        ['line' => 10, 'column' => 2],
     ],
     'path' => [
         'path',
         'to',
-        'fieldWithException'
+        'fieldWithException',
     ]
 ];
 ```
@@ -125,24 +117,20 @@ $result = GraphQL::executeQuery(/*args*/)->toArray($debug);
 This will make each error entry to look like this:
 
 ```php
-<?php
 [
     'debugMessage' => 'Actual exception message',
     'message' => 'Internal server error',
-    'extensions' => [
-        'category' => 'internal'
-    ],
     'locations' => [
-        ['line' => 10, 'column' => 2]
+        ['line' => 10, 'column' => 2],
     ],
     'path' => [
         'listField',
         0,
-        'fieldWithException'
+        'fieldWithException',
     ],
     'trace' => [
         /* Formatted original exception trace */
-    ]
+    ],
 ];
 ```
 

src/Error/ClientAware.php

@@ -5,32 +5,19 @@
 namespace GraphQL\Error;
 
 /**
- * This interface is used for [default error formatting](error-handling.md).
+ * Implementing ClientAware allows graphql-php to decide if this error is safe to be shown to clients.
  *
- * Only errors implementing this interface (and returning true from `isClientSafe()`)
- * will be formatted with original error message.
+ * Only errors that both implement this interface and return true from `isClientSafe()`
+ * will retain their original error message during formatting.
  *
- * All other errors will be formatted with generic "Internal server error".
+ * All other errors will have their message replaced with "Internal server error".
  */
 interface ClientAware
 {
     /**
-     * Returns true when exception message is safe to be displayed to a client.
-     *
-     * @return bool
-     *
-     * @api
-     */
-    public function isClientSafe();
-
-    /**
-     * Returns string describing a category of the error.
-     *
-     * Value "graphql" is reserved for errors produced by query parsing or validation, do not use it.
-     *
-     * @return string
+     * Is it safe to show the error message to clients?
      *
      * @api
      */
-    public function getCategory();
+    public function isClientSafe(): bool;
 }

src/Error/Error.php

@@ -34,11 +34,8 @@
  * Class extends standard PHP `\Exception`, so all standard methods of base `\Exception` class
  * are available in addition to those listed below.
  */
-class Error extends Exception implements JsonSerializable, ClientAware
+class Error extends Exception implements JsonSerializable, ClientAware, ProvidesExtensions
 {
-    const CATEGORY_GRAPHQL  = 'graphql';
-    const CATEGORY_INTERNAL = 'internal';
-
     /**
      * Lazily initialized.
      *
@@ -74,22 +71,18 @@ class Error extends Exception implements JsonSerializable, ClientAware
     /** @var int[] */
     private $positions;
 
-    /** @var bool */
-    private $isClientSafe;
-
-    /** @var string */
-    protected $category;
+    private bool $isClientSafe;
 
-    /** @var mixed[]|null */
-    protected $extensions;
+    /** @var array<string, mixed> */
+    protected array $extensions;
 
     /**
      * @param string                       $message
      * @param Node|Node[]|Traversable|null $nodes
      * @param mixed[]                      $positions
      * @param mixed[]|null                 $path
      * @param Throwable                    $previous
-     * @param mixed[]                      $extensions
+     * @param array<string, mixed>         $extensions
      */
     public function __construct(
         $message = '',
@@ -104,31 +97,31 @@ public function __construct(
 
         // Compute list of blame nodes.
         if ($nodes instanceof Traversable) {
-            $nodes = iterator_to_array($nodes);
-        } elseif ($nodes !== null && ! is_array($nodes)) {
-            $nodes = [$nodes];
+            $this->nodes = iterator_to_array($nodes);
+        } elseif (is_array($nodes)) {
+            $this->nodes = $nodes;
+        } elseif ($nodes !== null) {
+            $this->nodes = [$nodes];
         }
 
-        $this->nodes      = $nodes;
-        $this->source     = $source;
-        $this->positions  = $positions;
-        $this->path       = $path;
-        $this->extensions = count($extensions) > 0 ? $extensions : (
-        $previous instanceof self
-            ? $previous->extensions
-            : []
-        );
+        $this->source    = $source;
+        $this->positions = $positions;
+        $this->path      = $path;
+
+        if (count($extensions) > 0) {
+            $this->extensions = $extensions;
+        } elseif ($previous instanceof ProvidesExtensions) {
+            $this->extensions = $previous->getExtensions();
+        } else {
+            $this->extensions = [];
+        }
 
         if ($previous instanceof ClientAware) {
             $this->isClientSafe = $previous->isClientSafe();
-            $cat                = $previous->getCategory();
-            $this->category     = $cat === '' || $cat === null  ? self::CATEGORY_INTERNAL : $cat;
         } elseif ($previous !== null) {
             $this->isClientSafe = false;
-            $this->category     = self::CATEGORY_INTERNAL;
         } else {
             $this->isClientSafe = true;
-            $this->category     = self::CATEGORY_GRAPHQL;
         }
     }
 
@@ -195,22 +188,11 @@ public static function formatError(Error $error)
         return $error->toSerializableArray();
     }
 
-    /**
-     * @inheritdoc
-     */
-    public function isClientSafe()
+    public function isClientSafe(): bool
     {
         return $this->isClientSafe;
     }
 
-    /**
-     * @inheritdoc
-     */
-    public function getCategory()
-    {
-        return $this->category;
-    }
-
     public function getSource(): ?Source
     {
         if ($this->source === null) {
@@ -320,10 +302,7 @@ public function getPath()
         return $this->path;
     }
 
-    /**
-     * @return mixed[]
-     */
-    public function getExtensions()
+    public function getExtensions(): array
     {
         return $this->extensions;
     }