[RFC] FILTER_THROW_ON_FAILURE (php#18896)

https://wiki.php.net/rfc/filter_throw_on_failure

Author: DanielEScherzer

ext/filter/callback_filter.c

@@ -16,7 +16,7 @@
 
 #include "php_filter.h"
 
-void php_filter_callback(PHP_INPUT_FILTER_PARAM_DECL)
+zend_result php_filter_callback(PHP_INPUT_FILTER_PARAM_DECL)
 {
 	zval retval;
 	int status;
@@ -25,7 +25,7 @@ void php_filter_callback(PHP_INPUT_FILTER_PARAM_DECL)
 		zend_type_error("%s(): Option must be a valid callback", get_active_function_name());
 		zval_ptr_dtor(value);
 		ZVAL_NULL(value);
-		return;
+		return SUCCESS;
 	}
 
 	status = call_user_function(NULL, NULL, option_array, &retval, 1, value);
@@ -37,4 +37,5 @@ void php_filter_callback(PHP_INPUT_FILTER_PARAM_DECL)
 		zval_ptr_dtor(value);
 		ZVAL_NULL(value);
 	}
+	return SUCCESS;
 }

ext/filter/filter.c

@@ -30,11 +30,12 @@ ZEND_DECLARE_MODULE_GLOBALS(filter)
 #include "zend_attributes.h"
 #include "filter_private.h"
 #include "filter_arginfo.h"
+#include "zend_exceptions.h"
 
 typedef struct filter_list_entry {
 	const char *name;
 	int    id;
-	void (*function)(PHP_INPUT_FILTER_PARAM_DECL);
+	zend_result (*function)(PHP_INPUT_FILTER_PARAM_DECL);
 } filter_list_entry;
 
 /* {{{ filter_list */
@@ -77,6 +78,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,
@@ -160,6 +164,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;
 }
 /* }}} */
@@ -251,6 +258,16 @@ 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)
+				);
+				ZVAL_NULL(value);
+				return;
+			}
 			/* #67167: doesn't return null on failure for objects */
 			if (flags & FILTER_NULL_ON_FAILURE) {
 				ZVAL_NULL(value);
@@ -264,7 +281,29 @@ static void php_zval_filter(zval *value, zend_long filter, zend_long flags, zval
 	/* Here be strings */
 	convert_to_string(value);
 
-	filter_func.function(value, flags, options, charset);
+	zend_string *copy_for_throwing = NULL;
+	if (flags & FILTER_THROW_ON_FAILURE) {
+		copy_for_throwing = zend_string_copy(Z_STR_P(value));
+	}
+
+	zend_result result = filter_func.function(value, flags, options, charset);
+
+	if (flags & FILTER_THROW_ON_FAILURE) {
+		ZEND_ASSERT(copy_for_throwing != NULL);
+		if (result == FAILURE) {
+			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 &&
@@ -450,7 +489,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;
@@ -492,10 +532,28 @@ 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)) {
+		zval_ptr_dtor(filtered);
+		ZVAL_NULL(filtered);
+		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) {
+				ZVAL_NULL(filtered);
+				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);
@@ -506,6 +564,17 @@ static void php_filter_call(
 		return;
 	}
 	if (filter_flags & FILTER_REQUIRE_ARRAY) {
+		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)",
+				zend_zval_value_name(filtered)
+			);
+			zval_ptr_dtor(filtered);
+			ZVAL_NULL(filtered);
+			return;
+		}
 		zval_ptr_dtor(filtered);
 		if (filter_flags & FILTER_NULL_ON_FAILURE) {
 			ZVAL_NULL(filtered);
@@ -516,6 +585,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);
@@ -530,7 +603,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;
@@ -557,8 +630,12 @@ 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)) {
+					RETURN_THROWS();
+				}
 				zend_hash_update(Z_ARRVAL_P(return_value), arg_key, &nval);
 			}
 		} ZEND_HASH_FOREACH_END();
@@ -598,11 +675,35 @@ 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_ex(
+				php_filter_failed_exception_ce,
+				0,
+				"input value '%s' not found",
+				ZSTR_VAL(var)
+			);
+			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
@@ -626,7 +727,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);
 }
 /* }}} */
 
@@ -652,7 +753,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,17 +94,26 @@
 || (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. Returning FAILURE
+ * from the filter handler indicates that validation failed *and* an exception
+ * should thus be thrown. */
 #define RETURN_VALIDATION_FAILED \
 	if (EG(exception)) { \
-		return; \
+		return SUCCESS; \
+	} else if (flags & FILTER_THROW_ON_FAILURE) { \
+		zval_ptr_dtor(value); \
+		ZVAL_NULL(value); \
+		return FAILURE; \
 	} else if (flags & FILTER_NULL_ON_FAILURE) { \
 		zval_ptr_dtor(value); \
 		ZVAL_NULL(value); \
 	} else { \
 		zval_ptr_dtor(value); \
 		ZVAL_FALSE(value); \
 	}	\
-	return;	\
+	return SUCCESS;	\
 
 #define PHP_FILTER_TRIM_DEFAULT(p, len) PHP_FILTER_TRIM_DEFAULT_EX(p, len, 1);