[RFC} FILTER_THROW_ON_FAILURE

Author: DanielEScherzer

ext/filter/filter.c

@@ -29,6 +29,7 @@ ZEND_DECLARE_MODULE_GLOBALS(filter)
 
 #include "filter_private.h"
 #include "filter_arginfo.h"
+#include "zend_exceptions.h"
 
 typedef struct filter_list_entry {
 	const char *name;
@@ -76,6 +77,9 @@ static const filter_list_entry filter_list[] = {
 static unsigned int php_sapi_filter(int arg, const char *var, char **val, size_t val_len, size_t *new_val_len);
 static unsigned int php_sapi_filter_init(void);
 
+zend_class_entry *php_filter_exception_ce;
+zend_class_entry *php_filter_failed_exception_ce;
+
 /* {{{ filter_module_entry */
 zend_module_entry filter_module_entry = {
 	STANDARD_MODULE_HEADER,
@@ -159,6 +163,9 @@ PHP_MINIT_FUNCTION(filter)
 
 	sapi_register_input_filter(php_sapi_filter, php_sapi_filter_init);
 
+	php_filter_exception_ce = register_class_Filter_FilterException(zend_ce_exception);
+	php_filter_failed_exception_ce = register_class_Filter_FilterFailedException(php_filter_exception_ce);
+
 	return SUCCESS;
 }
 /* }}} */
@@ -250,6 +257,15 @@ static void php_zval_filter(zval *value, zend_long filter, zend_long flags, zval
 		ce = Z_OBJCE_P(value);
 		if (!ce->__tostring) {
 			zval_ptr_dtor(value);
+			if (flags & FILTER_THROW_ON_FAILURE) {
+				zend_throw_exception_ex(
+					php_filter_failed_exception_ce,
+					0,
+					"filter validation failed: object of type %s has no __toString() method",
+					ZSTR_VAL(ce->name)
+				);
+				return;
+			}
 			/* #67167: doesn't return null on failure for objects */
 			if (flags & FILTER_NULL_ON_FAILURE) {
 				ZVAL_NULL(value);
@@ -263,8 +279,30 @@ static void php_zval_filter(zval *value, zend_long filter, zend_long flags, zval
 	/* Here be strings */
 	convert_to_string(value);
 
+	zend_string *copy_for_throwing = NULL;
+	if (flags & FILTER_THROW_ON_FAILURE) {
+		copy_for_throwing = zend_string_copy(Z_STR_P(value));
+	}
+
 	filter_func.function(value, flags, options, charset);
 
+	if (flags & FILTER_THROW_ON_FAILURE) {
+		ZEND_ASSERT(copy_for_throwing != NULL);
+		if (Z_ISERROR_P(value)) {
+			zend_throw_exception_ex(
+				php_filter_failed_exception_ce,
+				0,
+				"filter validation failed: filter %s not satisfied by %s",
+				filter_func.name,
+				ZSTR_VAL(copy_for_throwing)
+			);
+			zend_string_delref(copy_for_throwing);
+			return;
+		}
+		zend_string_delref(copy_for_throwing);
+		copy_for_throwing = NULL;
+	}
+
 handle_default:
 	if (options && Z_TYPE_P(options) == IS_ARRAY &&
 		((flags & FILTER_NULL_ON_FAILURE && Z_TYPE_P(value) == IS_NULL) ||
@@ -449,7 +487,8 @@ PHP_FUNCTION(filter_has_var)
 
 static void php_filter_call(
 	zval *filtered, zend_long filter, HashTable *filter_args_ht, zend_long filter_args_long,
-	zend_long filter_flags
+	zend_long filter_flags,
+	uint32_t options_arg_num
 ) /* {{{ */ {
 	zval *options = NULL;
 	char *charset = NULL;
@@ -491,10 +530,25 @@ static void php_filter_call(
 		}
 	}
 
+	/* Cannot use both FILTER_NULL_ON_FAILURE and FILTER_THROW_ON_FAILURE */
+	if ((filter_flags & FILTER_NULL_ON_FAILURE) && (filter_flags & FILTER_THROW_ON_FAILURE)) {
+		zend_argument_value_error(
+			options_arg_num,
+			"cannot use both FILTER_NULL_ON_FAILURE and FILTER_THROW_ON_FAILURE"
+		);
+		return;
+	}
+
 	if (Z_TYPE_P(filtered) == IS_ARRAY) {
 		if (filter_flags & FILTER_REQUIRE_SCALAR) {
 			zval_ptr_dtor(filtered);
-			if (filter_flags & FILTER_NULL_ON_FAILURE) {
+			if (filter_flags & FILTER_THROW_ON_FAILURE) {
+				zend_throw_exception(
+					php_filter_failed_exception_ce,
+					"filter validation failed: not a scalar value (got an array)",
+					0
+				);
+			} else if (filter_flags & FILTER_NULL_ON_FAILURE) {
 				ZVAL_NULL(filtered);
 			} else {
 				ZVAL_FALSE(filtered);
@@ -505,8 +559,16 @@ static void php_filter_call(
 		return;
 	}
 	if (filter_flags & FILTER_REQUIRE_ARRAY) {
+		const char *got_type = zend_zval_value_name(filtered);
 		zval_ptr_dtor(filtered);
-		if (filter_flags & FILTER_NULL_ON_FAILURE) {
+		if (filter_flags & FILTER_THROW_ON_FAILURE) {
+			zend_throw_exception_ex(
+				php_filter_failed_exception_ce,
+				0,
+				"filter validation failed: not an array (got %s)",
+				got_type
+			);
+		} else if (filter_flags & FILTER_NULL_ON_FAILURE) {
 			ZVAL_NULL(filtered);
 		} else {
 			ZVAL_FALSE(filtered);
@@ -515,6 +577,10 @@ static void php_filter_call(
 	}
 
 	php_zval_filter(filtered, filter, filter_flags, options, charset);
+	// Don't wrap in an array if we are throwing an exception
+	if (EG(exception)) {
+		return;
+	}
 	if (filter_flags & FILTER_FORCE_ARRAY) {
 		zval tmp;
 		ZVAL_COPY_VALUE(&tmp, filtered);
@@ -529,7 +595,7 @@ static void php_filter_array_handler(zval *input, HashTable *op_ht, zend_long op
 ) /* {{{ */ {
 	if (!op_ht) {
 		ZVAL_DUP(return_value, input);
-		php_filter_call(return_value, -1, NULL, op_long, FILTER_REQUIRE_ARRAY);
+		php_filter_call(return_value, -1, NULL, op_long, FILTER_REQUIRE_ARRAY, 2);
 	} else {
 		array_init(return_value);
 		zend_string *arg_key;
@@ -556,8 +622,13 @@ static void php_filter_array_handler(zval *input, HashTable *op_ht, zend_long op
 				php_filter_call(&nval, -1,
 					Z_TYPE_P(arg_elm) == IS_ARRAY ? Z_ARRVAL_P(arg_elm) : NULL,
 					Z_TYPE_P(arg_elm) == IS_ARRAY ? 0 : zval_get_long(arg_elm),
-					FILTER_REQUIRE_SCALAR
+					FILTER_REQUIRE_SCALAR,
+					2
 				);
+				if (EG(exception)) {
+					zval_ptr_dtor(&nval);
+					RETURN_THROWS();
+				}
 				zend_hash_update(Z_ARRVAL_P(return_value), arg_key, &nval);
 			}
 		} ZEND_HASH_FOREACH_END();
@@ -597,11 +668,34 @@ PHP_FUNCTION(filter_input)
 		if (!filter_args_ht) {
 			filter_flags = filter_args_long;
 		} else {
-			zval *option, *opt, *def;
+			zval *option;
 			if ((option = zend_hash_str_find(filter_args_ht, "flags", sizeof("flags") - 1)) != NULL) {
 				filter_flags = zval_get_long(option);
 			}
+		}
+
+		/* Cannot use both FILTER_NULL_ON_FAILURE and FILTER_THROW_ON_FAILURE */
+		if ((filter_flags & FILTER_NULL_ON_FAILURE) && (filter_flags & FILTER_THROW_ON_FAILURE)) {
+			zend_argument_value_error(
+				4,
+				"cannot use both FILTER_NULL_ON_FAILURE and FILTER_THROW_ON_FAILURE"
+			);
+			RETURN_THROWS();
+		}
+
+		if (filter_flags & FILTER_THROW_ON_FAILURE) {
+			zend_throw_exception(
+				php_filter_failed_exception_ce,
+				"input value not found",
+				0
+			);
+			RETURN_THROWS();
+		}
 
+		/* FILTER_THROW_ON_FAILURE overrides defaults, needs to be checked
+		 * before the default is used. */
+		if (filter_args_ht) {
+			zval *opt, *def;
 			if ((opt = zend_hash_str_find_deref(filter_args_ht, "options", sizeof("options") - 1)) != NULL &&
 				Z_TYPE_P(opt) == IS_ARRAY &&
 				(def = zend_hash_str_find_deref(Z_ARRVAL_P(opt), "default", sizeof("default") - 1)) != NULL
@@ -625,7 +719,7 @@ PHP_FUNCTION(filter_input)
 
 	ZVAL_DUP(return_value, tmp);
 
-	php_filter_call(return_value, filter, filter_args_ht, filter_args_long, FILTER_REQUIRE_SCALAR);
+	php_filter_call(return_value, filter, filter_args_ht, filter_args_long, FILTER_REQUIRE_SCALAR, 4);
 }
 /* }}} */
 
@@ -651,7 +745,7 @@ PHP_FUNCTION(filter_var)
 
 	ZVAL_DUP(return_value, data);
 
-	php_filter_call(return_value, filter, filter_args_ht, filter_args_long, FILTER_REQUIRE_SCALAR);
+	php_filter_call(return_value, filter, filter_args_ht, filter_args_long, FILTER_REQUIRE_SCALAR, 3);
 }
 /* }}} */
 

ext/filter/filter.stub.php

@@ -2,6 +2,7 @@
 
 /** @generate-class-entries */
 
+namespace {
 /**
  * @var int
  * @cvalue PARSE_POST
@@ -54,6 +55,11 @@
  * @cvalue FILTER_NULL_ON_FAILURE
  */
 const FILTER_NULL_ON_FAILURE = UNKNOWN;
+/**
+ * @var int
+ * @cvalue FILTER_THROW_ON_FAILURE
+ */
+const FILTER_THROW_ON_FAILURE = UNKNOWN;
 
 /**
  * @var int
@@ -313,3 +319,13 @@ function filter_var_array(array $array, array|int $options = FILTER_DEFAULT, boo
 function filter_list(): array {}
 
 function filter_id(string $name): int|false {}
+
+}
+
+namespace Filter {
+
+	class FilterException extends \Exception {}
+
+	class FilterFailedException extends FilterException {}
+
+}

ext/filter/filter_arginfo.h

@@ -24,6 +24,7 @@
 
 #define FILTER_FORCE_ARRAY			0x4000000
 #define FILTER_NULL_ON_FAILURE			0x8000000
+#define FILTER_THROW_ON_FAILURE			0x10000000
 
 #define FILTER_FLAG_ALLOW_OCTAL             0x0001
 #define FILTER_FLAG_ALLOW_HEX               0x0002
@@ -50,7 +51,7 @@
 #define FILTER_FLAG_IPV6                    0x00200000
 #define FILTER_FLAG_NO_RES_RANGE            0x00400000
 #define FILTER_FLAG_NO_PRIV_RANGE           0x00800000
-#define FILTER_FLAG_GLOBAL_RANGE            0x10000000
+#define FILTER_FLAG_GLOBAL_RANGE            0x20000000
 
 #define FILTER_FLAG_HOSTNAME               0x100000
 
@@ -93,9 +94,16 @@
 || (id >= FILTER_VALIDATE_ALL && id <= FILTER_VALIDATE_LAST) \
 || id == FILTER_CALLBACK)
 
+
+/* When using FILTER_THROW_ON_FAILURE, we can't actually throw the error here
+ * because we don't have access to the name of the filter. Use ZVAL_ERROR()
+ * so that we can easily identify places where we want to throw. */
 #define RETURN_VALIDATION_FAILED \
 	if (EG(exception)) { \
 		return; \
+	} else if (flags & FILTER_THROW_ON_FAILURE) { \
+		zval_ptr_dtor(value); \
+		ZVAL_ERROR(value); \
 	} else if (flags & FILTER_NULL_ON_FAILURE) { \
 		zval_ptr_dtor(value); \
 		ZVAL_NULL(value); \

ext/filter/filter_private.h

@@ -0,0 +1,29 @@
+--TEST--
+FILTER_THROW_ON_FAILURE: filter_input_array() failure
+--EXTENSIONS--
+filter
+--GET--
+a=1
+--FILE--
+<?php
+
+echo "\nvalidation fails (array type check)\n";
+try {
+	filter_input_array(INPUT_GET, ['a' => ['flags' => FILTER_REQUIRE_ARRAY | FILTER_THROW_ON_FAILURE]]);
+} catch (Filter\FilterFailedException $e) {
+	echo get_class($e) . ": " . $e->getMessage() . "\n";
+}
+
+echo "\nvalidation fails (filter value)\n";
+try {
+	filter_input_array(INPUT_GET, ['a' => ['filter' => FILTER_VALIDATE_EMAIL, 'flags' => FILTER_THROW_ON_FAILURE]]);
+} catch (Filter\FilterFailedException $e) {
+	echo get_class($e) . ": " . $e->getMessage() . "\n";
+}
+?>
+--EXPECT--
+validation fails (array type check)
+Filter\FilterFailedException: filter validation failed: not an array (got string)
+
+validation fails (filter value)
+Filter\FilterFailedException: filter validation failed: filter validate_email not satisfied by 1

ext/filter/tests/throw-on-failure/filter_input_array_failure.phpt

@@ -0,0 +1,39 @@
+--TEST--
+FILTER_THROW_ON_FAILURE: filter_input() failure
+--EXTENSIONS--
+filter
+--GET--
+a=1
+--FILE--
+<?php
+
+echo "missing value\n";
+try {
+	filter_input(INPUT_GET, 'b', FILTER_DEFAULT, FILTER_THROW_ON_FAILURE);
+} catch (Filter\FilterFailedException $e) {
+	echo get_class($e) . ": " . $e->getMessage() . "\n";
+}
+
+echo "\nvalidation fails (array type check)\n";
+try {
+	filter_input(INPUT_GET, 'a', FILTER_DEFAULT, FILTER_REQUIRE_ARRAY | FILTER_THROW_ON_FAILURE);
+} catch (Filter\FilterFailedException $e) {
+	echo get_class($e) . ": " . $e->getMessage() . "\n";
+}
+
+echo "\nvalidation fails (filter value)\n";
+try {
+	filter_input(INPUT_GET, 'a', FILTER_VALIDATE_EMAIL, FILTER_THROW_ON_FAILURE);
+} catch (Filter\FilterFailedException $e) {
+	echo get_class($e) . ": " . $e->getMessage() . "\n";
+}
+?>
+--EXPECT--
+missing value
+Filter\FilterFailedException: input value not found
+
+validation fails (array type check)
+Filter\FilterFailedException: filter validation failed: not an array (got string)
+
+validation fails (filter value)
+Filter\FilterFailedException: filter validation failed: filter validate_email not satisfied by 1