Added explanatory comments to filter_input and filter_input_array to document

why some code that looks intuitively wrong is actually correct. Related to
bug #51344 (FILTER_NULL_ON_FAILURE flag automatically set in filter_input()
functions).

diff --git a/ext/filter/filter.c b/ext/filter/filter.c
index 2ffe70499bcf738805991d301f7c6bbcafd97896..d6f2090b3a4b58123ccffab4ed5513d0cc8ab1c8 100644 (file)
--- a/ext/filter/filter.c
+++ b/ext/filter/filter.c
@@ -780,6 +780,12 @@ PHP_FUNCTION(filter_input)
                                return;
                        }
                }
+
+               /* The FILTER_NULL_ON_FAILURE flag inverts the usual return values of
+                * the function: normally when validation fails false is returned, and
+                * when the input value doesn't exist NULL is returned. With the flag
+                * set, NULL and false should be returned, respectively. Ergo, although
+                * the code below looks incorrect, it's actually right. */
                if (filter_flags & FILTER_NULL_ON_FAILURE) {
                        RETURN_FALSE;
                } else {
@@ -846,6 +852,12 @@ PHP_FUNCTION(filter_input_array)
                                PHP_FILTER_GET_LONG_OPT(option, filter_flags);
                        }
                }
+
+               /* The FILTER_NULL_ON_FAILURE flag inverts the usual return values of
+                * the function: normally when validation fails false is returned, and
+                * when the input value doesn't exist NULL is returned. With the flag
+                * set, NULL and false should be returned, respectively. Ergo, although
+                * the code below looks incorrect, it's actually right. */
                if (filter_flags & FILTER_NULL_ON_FAILURE) {
                        RETURN_FALSE;
                } else {