document (re-)throwing behaviour from exception filter

Author: stesie

README.md

@@ -413,5 +413,7 @@ via `getPrevious` method.
 
 Consider that the JS code has access to methods like `getTrace` on the exception
 object.  This might be unwanted behaviour, if you execute untrusted code.
-Using `setExceptionFilter` method a callable can be provided, that converts
-the PHP exception to not expose unwanted information.
+Using `setExceptionFilter` method a callable can be provided, that may convert
+the PHP exception to some other value that is safe to expose.  The filter may
+also decide not to propagate the exception to JS at all by either re-throwing
+the passed exception or throwing another exception.

tests/exception_filter_004.phpt

@@ -1,5 +1,5 @@
 --TEST--
-Test V8::setExceptionFilter() : Filter handling on exception in factory
+Test V8::setExceptionFilter() : Filter handling on exception in converter
 --SKIPIF--
 <?php require_once(dirname(__FILE__) . '/skipif.inc'); ?>
 --FILE--

tests/exception_filter_006.phpt

@@ -0,0 +1,38 @@
+--TEST--
+Test V8::setExceptionFilter() : re-throw exception in exception filter
+--SKIPIF--
+<?php require_once(dirname(__FILE__) . '/skipif.inc'); ?>
+--FILE--
+<?php
+class myv8 extends V8Js
+{
+        public function throwException(string $message) {
+                throw new Exception($message);
+        }
+}
+
+$v8 = new myv8();
+$v8->setExceptionFilter(function (Throwable $ex) {
+	// re-throw exception so it is not forwarded
+        throw $ex;
+});
+
+try {
+        $v8->executeString('
+                try {
+                        PHP.throwException("Oops");
+                        print("done\\n");
+                }
+                catch (e) {
+                        print("caught\\n");
+                        var_dump(e);
+                }
+        ', null, V8Js::FLAG_PROPAGATE_PHP_EXCEPTIONS);
+} catch (Exception $ex) {
+        echo "caught in php: " . $ex->getMessage() . PHP_EOL;
+}
+?>
+===EOF===
+--EXPECT--
+caught in php: Oops
+===EOF===