feat(api): improved API errors with formatted RFC 7807 Problem Details JSON responses (#3830)

thorsten · thorsten · commit 741152d56a6e · 2026-01-03T13:51:57.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,13 +9,15 @@ This is a log of major user-visible changes in each phpMyFAQ release.
 ### phpMyFAQ v4.2.0-dev - unreleased
 
 - changed PHP requirement to PHP 8.4 or later (Thorsten)
+- added Symfony Router for frontend (Thorsten)
+- improved API errors with formatted RFC 7807 Problem Details JSON responses (Thorsten)
 
 ### phpMyFAQ v4.1.0-RC.2 - unreleased
 
 - changed PHP requirement to PHP 8.3 or later (Thorsten)
 - added configuration to edit robots.txt (Thorsten)
 - added configuration to edit llms.txt (Thorsten)
-- added Symfony Routing for administration backend (Thorsten)
+- added Symfony Router for administration backend (Thorsten)
 - added code snippets plugin with syntax highlighting in WYSIWYG editor (Thorsten)
 - added an administration view for orphaned FAQs (Thorsten)
 - added plugin administration backend (Thorsten)
diff --git a/phpmyfaq/.htaccess b/phpmyfaq/.htaccess
@@ -100,27 +100,20 @@ Header set Access-Control-Allow-Headers "Content-Type, Authorization"
     RewriteBase /
     # Block zip files in content directory
     RewriteRule ^content/.*\.zip$ - [F,L]
-
     # Exclude assets from being handled by Symfony Router
     RewriteRule ^admin/assets($|/) - [L]
-
     # Error pages
     ErrorDocument 404 /404.html
-
     # Administration API
     RewriteRule ^admin/api/ admin/api/index.php [L,QSA]
-
     # Administration pages (redirect /admin to /admin/)
     RewriteRule ^admin$ admin/ [R=301,L]
     RewriteRule ^admin/ admin/index.php [L,QSA]
-
     # API routes (all API endpoints)
     RewriteRule ^api/ api/index.php [L,QSA]
-
     # Setup pages
     RewriteRule ^setup/ setup/index.php [L,QSA]
     RewriteRule ^update$ update/ [R=301,L]
-
     # Front controller: route all other requests to index.php (Symfony Router)
     # Skip if the file or directory exists
     RewriteCond %{REQUEST_FILENAME} !-f
diff --git a/phpmyfaq/src/phpMyFAQ/Api/ProblemDetails.php b/phpmyfaq/src/phpMyFAQ/Api/ProblemDetails.php
@@ -0,0 +1,58 @@
+<?php
+
+/**
+ *  The ProblemDetails class for API error responses
+ *
+ *  This Source Code Form is subject to the terms of the Mozilla Public License,
+ *  v. 2.0. If a copy of the MPL was not distributed with this file, You can
+ *  obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ *  @package   phpMyFAQ
+ *  @author    Thorsten Rinne <thorsten@phpmyfaq.de>
+ *  @copyright 2026 phpMyFAQ Team
+ *  @license   https://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
+ *  @link      https://www.phpmyfaq.de
+ *  @since     2026-01-03
+ */
+
+declare(strict_types=1);
+
+namespace phpMyFAQ\Api;
+
+final readonly class ProblemDetails
+{
+    public function __construct(
+        public string $type,
+        public string $title,
+        public int $status,
+        public string $detail,
+        public string $instance,
+        public ?string $code = null,
+        public ?array $errors = null, // field-level errors, optional
+        public ?string $traceId = null, // correlation id, optional
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        $data = [
+            'type' => $this->type,
+            'title' => $this->title,
+            'status' => $this->status,
+            'detail' => $this->detail,
+            'instance' => $this->instance,
+        ];
+
+        if ($this->code !== null) {
+            $data['code'] = $this->code;
+        }
+        if ($this->errors !== null) {
+            $data['errors'] = $this->errors;
+        }
+        if ($this->traceId !== null) {
+            $data['traceId'] = $this->traceId;
+        }
+
+        return $data;
+    }
+}
diff --git a/phpmyfaq/src/phpMyFAQ/Application.php b/phpmyfaq/src/phpMyFAQ/Application.php
@@ -19,6 +19,7 @@
 
 namespace phpMyFAQ;
 
+use phpMyFAQ\Api\ProblemDetails;
 use phpMyFAQ\Controller\Exception\ForbiddenException;
 use phpMyFAQ\Core\Exception;
 use Symfony\Component\DependencyInjection\ContainerInterface;
@@ -139,15 +140,14 @@ private function handleRequest(
             $response->setStatusCode(Response::HTTP_OK);
             $response = call_user_func_array($controller, $arguments);
         } catch (ResourceNotFoundException $exception) {
-            // For API requests, return simple text/JSON response
+            // For API requests, return RFC 7807 JSON response
             if ($this->isApiContext) {
-                $message = Environment::isDebugMode()
-                    ? $this->formatExceptionMessage(
-                        template: 'Not Found: :message at line :line at :file',
-                        exception: $exception,
-                    )
-                    : 'Not Found';
-                $response = new Response(content: $message, status: Response::HTTP_NOT_FOUND);
+                $response = $this->createProblemDetailsResponse(
+                    request: $request,
+                    status: Response::HTTP_NOT_FOUND,
+                    exception: $exception,
+                    defaultDetail: 'The requested resource was not found.',
+                );
             } else {
                 // For web requests, forward to the PageNotFoundController
                 try {
@@ -170,31 +170,51 @@ private function handleRequest(
                     $response = new Response(content: $message, status: Response::HTTP_NOT_FOUND);
                 }
             }
-        } catch (UnauthorizedHttpException) {
-            $response = new RedirectResponse(url: './login');
-            if (str_contains(haystack: $urlMatcher->getContext()->getBaseUrl(), needle: '/api')) {
-                $response = new Response(
-                    content: json_encode(value: ['error' => 'Unauthorized access']),
+        } catch (UnauthorizedHttpException $exception) {
+            if ($this->isApiContext) {
+                $response = $this->createProblemDetailsResponse(
+                    request: $request,
                     status: Response::HTTP_UNAUTHORIZED,
-                    headers: ['Content-Type' => 'application/json'],
+                    exception: $exception,
+                    defaultDetail: 'Unauthorized access.',
                 );
+            } else {
+                $response = new RedirectResponse(url: './login');
             }
         } catch (ForbiddenException $exception) {
-            $message = Environment::isDebugMode()
-                ? $this->formatExceptionMessage(
-                    template: 'An error occurred: :message at line :line at :file',
+            if ($this->isApiContext) {
+                $response = $this->createProblemDetailsResponse(
+                    request: $request,
+                    status: Response::HTTP_FORBIDDEN,
                     exception: $exception,
-                )
-                : 'Bad Request';
-            $response = new Response(content: $message, status: Response::HTTP_FORBIDDEN);
+                    defaultDetail: 'Access to this resource is forbidden.',
+                );
+            } else {
+                $message = Environment::isDebugMode()
+                    ? $this->formatExceptionMessage(
+                        template: 'An error occurred: :message at line :line at :file',
+                        exception: $exception,
+                    )
+                    : 'Forbidden';
+                $response = new Response(content: $message, status: Response::HTTP_FORBIDDEN);
+            }
         } catch (BadRequestException $exception) {
-            $message = Environment::isDebugMode()
-                ? $this->formatExceptionMessage(
-                    template: 'An error occurred: :message at line :line at :file',
+            if ($this->isApiContext) {
+                $response = $this->createProblemDetailsResponse(
+                    request: $request,
+                    status: Response::HTTP_BAD_REQUEST,
                     exception: $exception,
-                )
-                : 'Bad Request';
-            $response = new Response(content: $message, status: Response::HTTP_BAD_REQUEST);
+                    defaultDetail: 'The request could not be understood or was missing required parameters.',
+                );
+            } else {
+                $message = Environment::isDebugMode()
+                    ? $this->formatExceptionMessage(
+                        template: 'An error occurred: :message at line :line at :file',
+                        exception: $exception,
+                    )
+                    : 'Bad Request';
+                $response = new Response(content: $message, status: Response::HTTP_BAD_REQUEST);
+            }
         } catch (Throwable $exception) {
             // Log the error for debugging
             error_log(sprintf(
@@ -204,33 +224,22 @@ private function handleRequest(
                 $exception->getLine(),
             ));
 
-            $message = Environment::isDebugMode()
-                ? $this->formatExceptionMessage(
-                    template: 'Internal Server Error: :message at line :line at :file',
+            if ($this->isApiContext) {
+                $response = $this->createProblemDetailsResponse(
+                    request: $request,
+                    status: Response::HTTP_INTERNAL_SERVER_ERROR,
                     exception: $exception,
-                )
-                : 'Internal Server Error';
-
-            // Return JSON response for API requests
-            if (str_contains(haystack: $urlMatcher->getContext()->getBaseUrl(), needle: '/api')) {
-                $content = Environment::isDebugMode()
-                    ? json_encode(value: [
-                        'error' => 'Internal Server Error',
-                        'message' => $exception->getMessage(),
-                        'file' => $exception->getFile(),
-                        'line' => $exception->getLine(),
-                    ])
-                    : json_encode(value: ['error' => 'Internal Server Error']);
-
-                $response = new Response(content: $content, status: Response::HTTP_INTERNAL_SERVER_ERROR, headers: [
-                    'Content-Type' => 'application/json',
-                ]);
-
-                $response->send();
-                return;
+                    defaultDetail: 'An unexpected error occurred while processing your request.',
+                );
+            } else {
+                $message = Environment::isDebugMode()
+                    ? $this->formatExceptionMessage(
+                        template: 'Internal Server Error: :message at line :line at :file',
+                        exception: $exception,
+                    )
+                    : 'Internal Server Error';
+                $response = new Response(content: $message, status: Response::HTTP_INTERNAL_SERVER_ERROR);
             }
-
-            $response = new Response(content: $message, status: Response::HTTP_INTERNAL_SERVER_ERROR);
         }
 
         $response->send();
@@ -247,4 +256,61 @@ private function formatExceptionMessage(string $template, Throwable $exception):
             ':file' => $exception->getFile(),
         ]);
     }
+
+    /**
+     * Creates a ProblemDetails response for API errors.
+     */
+    private function createProblemDetailsResponse(
+        Request $request,
+        int $status,
+        Throwable $exception,
+        string $defaultDetail,
+    ): Response {
+        $configuration = $this->container->get(id: 'phpmyfaq.configuration');
+        $baseUrl = rtrim($configuration->getDefaultUrl(), '/');
+
+        $type = match ($status) {
+            Response::HTTP_BAD_REQUEST => $baseUrl . '/problems/bad-request',
+            Response::HTTP_UNAUTHORIZED => $baseUrl . '/problems/unauthorized',
+            Response::HTTP_FORBIDDEN => $baseUrl . '/problems/forbidden',
+            Response::HTTP_NOT_FOUND => $baseUrl . '/problems/not-found',
+            Response::HTTP_CONFLICT => $baseUrl . '/problems/conflict',
+            Response::HTTP_UNPROCESSABLE_ENTITY => $baseUrl . '/problems/validation-error',
+            Response::HTTP_TOO_MANY_REQUESTS => $baseUrl . '/problems/rate-limited',
+            Response::HTTP_INTERNAL_SERVER_ERROR => $baseUrl . '/problems/internal-server-error',
+            default => $baseUrl . '/problems/http-error',
+        };
+
+        $title = match ($status) {
+            Response::HTTP_BAD_REQUEST => 'Bad Request',
+            Response::HTTP_UNAUTHORIZED => 'Unauthorized',
+            Response::HTTP_FORBIDDEN => 'Forbidden',
+            Response::HTTP_NOT_FOUND => 'Resource not found',
+            Response::HTTP_CONFLICT => 'Conflict',
+            Response::HTTP_UNPROCESSABLE_ENTITY => 'Validation failed',
+            Response::HTTP_TOO_MANY_REQUESTS => 'Too many requests',
+            Response::HTTP_INTERNAL_SERVER_ERROR => 'Internal Server Error',
+            default => 'HTTP error',
+        };
+
+        $detail = Environment::isDebugMode()
+            ? $exception->getMessage() . ' at line ' . $exception->getLine() . ' in ' . $exception->getFile()
+            : $defaultDetail;
+
+        $problemDetails = new ProblemDetails(
+            type: $type,
+            title: $title,
+            status: $status,
+            detail: $detail,
+            instance: $request->getPathInfo(),
+        );
+
+        $response = new Response(
+            content: json_encode($problemDetails->toArray(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES),
+            status: $status,
+        );
+        $response->headers->set('Content-Type', 'application/problem+json');
+
+        return $response;
+    }
 }
diff --git a/tests/phpMyFAQ/ApplicationTest.php b/tests/phpMyFAQ/ApplicationTest.php
