Skip to content

Add examples for filter_var_array() and filter_input_array() - #5267

Merged
lacatoire merged 1 commit into
php:masterfrom
lacatoire:docs/filter-array-examples
Aug 25, 2026
Merged

Add examples for filter_var_array() and filter_input_array()#5267
lacatoire merged 1 commit into
php:masterfrom
lacatoire:docs/filter-array-examples

Conversation

@lacatoire

@lacatoire lacatoire commented Feb 5, 2026

Copy link
Copy Markdown
Member

Fixes #4218

Add examples for filter_var_array() and filter_input_array(), and correct the descriptions that those examples contradicted.

filter_var_array() gains two examples next to the existing one: applying a single filter to every entry of the array, and FILTER_CALLBACK. filter_input_array() had no examples at all and gains three: filtering GET input, filtering POST input (including a field that was not submitted, to show what add_empty does), and requesting an input type that is not populated.

Writing those examples surfaced several inaccuracies in the surrounding prose, corrected here:

  • filter_input_array() returns null, not false, when the input array designated by type is not populated. This does not depend on any flag.
  • A missing entry is always added as null when add_empty is true. The FILTER_NULL_ON_FAILURE flag does not turn it into false; that inversion applies to filter_input(), not to the array form.
  • filter_var_array() had no mention of add_empty or FILTER_NULL_ON_FAILURE in its return values, and stated that a failing entry is false without either qualifier.
  • With FILTER_FORCE_ARRAY, the failure value is wrapped in a one element array like any other result.
  • The options description is shared with filter_input_array() through xi:include, but referred to $array, a parameter that only exists on filter_var_array().
  • FILTER_REQUIRE_SCALAR is the default for both functions, so the flag in the first example only restates it. Said so, rather than leaving it to look like it changes the outcome.
  • Typo in the shared options description: "specifies and flags".

All outputs were reproduced on PHP 8.4.24, the request-dependent ones through the built-in web server.

Sources

  • null returned whenever the input array is absent, independently of any flag: ext/filter/filter.c, PHP_FUNCTION(filter_input_array), if (!array_input) { RETURN_NULL(); }
  • Missing keys always added as null: ext/filter/filter.c, php_filter_array_handler(), add_assoc_null_ex() is reached without the flags being read
  • FILTER_REQUIRE_SCALAR reinstated as the default whenever no *_ARRAY flag is given: ext/filter/filter.c, php_filter_call()

@lacatoire lacatoire closed this Mar 2, 2026
@lacatoire lacatoire reopened this Aug 21, 2026
@lacatoire
lacatoire force-pushed the docs/filter-array-examples branch 3 times, most recently from 8844be6 to 93533c0 Compare August 21, 2026 10:00
@lacatoire
lacatoire force-pushed the docs/filter-array-examples branch from 4719079 to 0eacf63 Compare August 25, 2026 10:01
@lacatoire
lacatoire merged commit 85264ba into php:master Aug 25, 2026
2 checks passed
@lacatoire
lacatoire deleted the docs/filter-array-examples branch August 25, 2026 10:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Filter: Add examples for filter_var_array() and filter_input_array()

1 participant