Merge pull request #506 from matslindh/rethrow-exceptions-in-index

* Add rethrowFinalException option (false) in default config
Introduces a setting to tell Imbo to throw the exception (again) instead of converting it to a fatal error. This allows us to keep the stack trace intact for development.

* Check rethrowFinalException and throw the exception if set

* Add documentation for `rethrowFinalException`

config/config.default.php

@@ -87,6 +87,17 @@
         return new Image\Identifier\Generator\RandomString();
     },
 
+    /**
+     * Keep errors as exceptions
+     *
+     * By default Imbo will catch any exceptions thrown internally and instead trigger a
+     * user error with the exception message. If you set this option to `true`, Imbo will
+     * instead rethrow the generated exception, giving you a full stack trace in your PHP
+     * error log. This should not be enabled in production, unless you have configured
+     * PHP in the recommended way with a separate error_log and display_errors=Off.
+     */
+    'rethrowFinalException' => false,
+
     /**
      * Whether to content negotiate images or not. If set to true, Imbo will try to find a
      * suitable image format based on the Accept-header received. If set to false, it will

docs/installation/configuration.rst

@@ -704,6 +704,26 @@ If what you want is for images to be delivered in the format they were uploaded
 
 You are still able to convert between formats by specifying an extension when requesting the image (`.jpg`, `.png`, `.gif` etc).
 
+.. _configuration-rethrow-exceptions:
+
+Rethrow any non-handled general exceptions - ``rethrowFinalException``
+----------------------------------------------------------------------
+
+If an exception occurs internally while Imbo is processing a request, the exception will be caught by the main application entry point and an appropriate error will be generated. This does however hide implementation details that can be useful if you're doing actual development on Imbo. This value is ``false`` by default.
+
+Setting this value to ``true`` will make Imbo rethrow the exception instead of swallowing the original exception and triggering an error. In the latter case the actual stack trace will be lost, and seeing which part of the code that actually failed will be harder in a log file.
+
+.. code-block:: php
+
+    <?php
+    return [
+        // ...
+
+        'rethrowFinalException' => true,
+
+        // ...
+    ];
+
 .. _configuration-trusted-proxies:
 
 Trusted proxies - ``trustedProxies``

public/index.php

@@ -22,5 +22,11 @@
     $application->run($config);
 } catch (BaseException $e) {
     header('HTTP/1.1 500 Internal Server Error');
-    trigger_error('Uncaught Exception with message: ' . $e->getMessage(), E_USER_ERROR);
+
+    // check if we should rethrow the exception and let PHP generate a fatal exception error with a proper stack trace
+    if (!empty($config['rethrowFinalException'])) {
+        throw $e;
+    } else {
+        trigger_error('Uncaught Exception with message: ' . $e->getMessage(), E_USER_ERROR);
+    }
 }