Adding global exception management with an ExceptionListener and basic functional tests to check that every error output in our application will have a JSON format

Author: juananrey

composer.json

@@ -12,6 +12,8 @@
         "symfony/yaml": "^4.0"
     },
     "require-dev": {
+        "symfony/browser-kit": "^4.0",
+        "symfony/css-selector": "^4.0",
         "symfony/dotenv": "^4.0",
         "symfony/phpunit-bridge": "^4.0"
     },

composer.lock

@@ -25,3 +25,7 @@ services:
 
     # add more service definitions when explicit configuration is needed
     # please note that last definitions always *replace* previous ones
+    App\EventListener\ExceptionListener:
+        arguments: ['%env(APP_ENV)%']
+        tags:
+            - { name: kernel.event_listener, event: kernel.exception }

config/services.yaml

@@ -0,0 +1,77 @@
+<?php
+
+namespace App\EventListener;
+
+use App\Exception\AppException;
+use App\Exception\ErrorCode\GlobalErrorCodes;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
+
+/**
+ * This listener receives ALL errors within the application and will always return the errors in a JSON format
+ */
+class ExceptionListener
+{
+    /**
+     * @var string
+     */
+    private $environment;
+
+    public function __construct(string $environment)
+    {
+        $this->environment = $environment;
+    }
+
+    public function onKernelException(GetResponseForExceptionEvent $event): void
+    {
+        $exception = $event->getException();
+        $response = new JsonResponse();
+
+        if ($exception instanceof AppException) {
+            $response->setStatusCode($exception->getHttpErrorCode());
+        } elseif ($exception instanceof HttpExceptionInterface) {
+            $response->setStatusCode($exception->getStatusCode());
+        } else {
+            $response->setStatusCode(Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+
+        if (false === $this->isProductionEnvironment()) {
+            $response->setJson(json_encode($this->buildErrorMessage($exception)));
+        } else {
+            $response->setJson(json_encode($this->buildErrorMessageForProductionClient($exception)));
+            // Here, use your application of preference to write ALL error logs (e.g. rollbar)
+        }
+
+        $event->setResponse($response);
+    }
+
+    private function buildErrorMessage(\Exception $exception): array
+    {
+        $errorMessage = [];
+        if ($exception instanceof AppException) {
+            $errorMessage['errorCode'] = $exception->getInternalErrorCode();
+        } else {
+            $errorMessage['errorCode'] = GlobalErrorCodes::INTERNAL_SERVER_DRAMA;
+        }
+
+        $errorMessage['errorMessage'] = $exception->getMessage();
+        $errorMessage['errorStackTrace'] = $exception->getTrace();
+
+        return $errorMessage;
+    }
+
+    private function buildErrorMessageForProductionClient(\Exception $exception): array
+    {
+        $errorMessage = $this->buildErrorMessage($exception);
+        unset($errorMessage['errorStackTrace']);
+
+        return $errorMessage;
+    }
+
+    private function isProductionEnvironment(): bool
+    {
+        return in_array($this->environment, ['pre', 'pro']);
+    }
+}

src/EventListener/ExceptionListener.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Exception;
+
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Global exception within our system, which will ALWAYS have a well-defined error code
+ * Such error code is defined in one of the files under ErrorCode/, which will be in this folder
+ */
+class AppException extends \Exception
+{
+    /**
+     * @var string
+     */
+    private $internalErrorCode;
+
+    /**
+     * @var int
+     */
+    private $httpErrorCode;
+
+    public function __construct(
+        string $internalErrorCode,
+        string $httpErrorCode = Response::HTTP_INTERNAL_SERVER_ERROR,
+        string $message = ''
+    ) {
+        $this->internalErrorCode = $internalErrorCode;
+        $this->httpErrorCode = $httpErrorCode;
+
+        parent::__construct($message);
+    }
+
+    public function getInternalErrorCode(): string
+    {
+        return $this->internalErrorCode;
+    }
+
+    public function getHttpErrorCode(): int
+    {
+        return $this->httpErrorCode;
+    }
+}

src/Exception/AppException.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace App\Exception\ErrorCode;
+
+final class GlobalErrorCodes
+{
+    const INTERNAL_SERVER_DRAMA = 'GLOB0001';
+}

src/Exception/ErrorCode/GlobalErrorCodes.php

@@ -44,6 +44,9 @@
             "ref": "aaddfdf43cdecd4cf91f992052d76c2cadc04543"
         }
     },
+    "symfony/browser-kit": {
+        "version": "v4.0.8"
+    },
     "symfony/cache": {
         "version": "v4.0.8"
     },
@@ -59,12 +62,18 @@
             "ref": "e3868d2f4a5104f19f844fe551099a00c6562527"
         }
     },
+    "symfony/css-selector": {
+        "version": "v4.0.8"
+    },
     "symfony/debug": {
         "version": "v4.0.8"
     },
     "symfony/dependency-injection": {
         "version": "v4.0.8"
     },
+    "symfony/dom-crawler": {
+        "version": "v4.0.8"
+    },
     "symfony/dotenv": {
         "version": "v4.0.8"
     },