====== PHP RFC: Deprecate Invalid Filter Options ======
  * Version: 0.9
  * Date: 2026-10-03
  * Author: Muhammed Arshid, arshidkv12@gmail.com
  * Status: Draft
  * Implementation: tbd
  * Discussion thread: tbd
  * Voting thread: tbd


===== Introduction =====
This RFC proposes improving error handling in the Filter extension when invalid option values are supplied to ''filter_var()'', ''filter_var_array()'', ''filter_input()'', and ''filter_input_array()''.

Currently, some option values are implicitly converted to integers. In particular, an invalid type such as an array supplied as ''flags'' may be silently converted instead of producing a clear error.

This proposal introduces a gradual migration path: PHP 8.7 will emit a deprecation notice for these invalid values, while PHP 8.8 will throw a ''ValueError'' instead.


===== Proposal =====
The Filter extension will no longer silently accept invalid values for options that are required to be integers.
The proposal applies to integer option handling in: ''filter_var'', ''filter_var_array'', ''filter_input'', ''filter_input_array''

  * In PHP 8.7: Emit an ''E_DEPRECATED'' notice.
  * In PHP 8.8: Throw a ''ValueError''.

==== Examples ====

The following examples demonstrate the proposed behavior for invalid option types and invalid filter/flag values across the affected Filter APIs.

==== filter_var() ====

An invalid string is supplied as ''flags'':

<PHP>
<?php
// E_DEPRECATED: filter_var: flags must be of type int, string given in %s
filter_var(
  '123',
  FILTER_VALIDATE_INT,
  [
    'flags' => 'abc', // Invalid flag type
  ]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice:
In PHP 8.8, this will throw a ''ValueError''.

An invalid integer is supplied as ''flags'':

<PHP>
<?php
// E_DEPRECATED: filter_var: Unknown flags with ID 10050 in %s
filter_var(
  '123',
  FILTER_VALIDATE_INT,
  [
    'flags' => 10050, // Invalid flag value
  ]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice:
In PHP 8.8, this will throw a ''ValueError''.

==== filter_var_array() ====

An invalid string is supplied as ''flags'':

<PHP>
<?php

// E_DEPRECATED: filter_var_array: flags must be of type int, string given in %s
filter_var_array(
  ['a' => '123'],
  [
    'a' => [
    'filter' => FILTER_VALIDATE_INT,
    'flags' => 'abc', // Invalid flag type
  ],
]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice:
In PHP 8.8, this will throw a ''ValueError''.

An invalid integer is supplied as ''flags'':

<PHP>
<?php

// E_DEPRECATED: filter_var_array: Unknown flags with ID 10050 in %s
filter_var_array(
  ['a' => '123'],
  [
  'a' => [
    'filter' => FILTER_VALIDATE_INT,
    'flags' => 10050, // Invalid flag value
  ],
]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice:
In PHP 8.8, this will throw a ''ValueError''.

==== filter_input() ====

The following example uses ''$_GET['a']'' as the input value:

<PHP>
<?php
// E_DEPRECATED: filter_input: flags must be of type int, string given in %s
filter_input(
  INPUT_GET,
  'a',
  FILTER_VALIDATE_INT,
  [
    'flags' => 'abc', // Invalid flag type
  ]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice.
In PHP 8.8, this will throw a ''ValueError''.

An invalid integer is supplied as ''flags'':

<PHP>
<?php

// E_DEPRECATED: filter_input: Unknown flags with ID 10050 in %s
filter_input(
  INPUT_GET,
  'a',
  FILTER_VALIDATE_INT,
  [
    'flags' => 10050, // Invalid flag value
  ]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice:
In PHP 8.8, this will throw a ''ValueError''.

==== filter_input_array() ====

The following example uses ''$_GET['a']'' as the input value:

<PHP>
<?php

// E_DEPRECATED: filter_input_array: filter must be of type int, string given in %s
filter_input_array(
INPUT_GET,
  [
    'a' => [
      'filter' => 'abc', // Invalid filter type
      'flags' => FILTER_FLAG_ALLOW_OCTAL
    ],
  ]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice:
In PHP 8.8, this will throw a ''ValueError''.

An invalid integer is supplied as ''filter'':

<PHP>
<?php

// E_DEPRECATED: filter_input_array: Unknown filter with ID 10050 in %s
filter_input_array(
INPUT_GET,
  [
    'a' => [
    'filter' => 10050, // Invalid filter value
    'flags' => FILTER_FLAG_ALLOW_OCTAL, 
  ],
]
);
?> </PHP>

In PHP 8.7, this emits an ''E_DEPRECATED'' notice:
In PHP 8.8, this will throw a ''ValueError''.


===== Backward Incompatible Changes =====
Applications that pass values of an invalid type to Filter options may be affected.

In particular, applications relying on implicit conversion of arrays or other invalid values to integers will need to change those values to the appropriate integer constants.

===== Proposed PHP Version(s) =====
PHP 8.7: Deprecation notice emitted.
PHP 8.8: Upgraded to ValueError.

===== RFC Impact =====
==== To the Ecosystem ====
IDEs and static analysis tools may benefit from the more explicit behavior because invalid option values will no longer be silently accepted.

Static analyzers may eventually detect invalid option types and report them before runtime.

==== To Existing Extensions ====
None

==== To SAPIs ====
None

===== Open Issues =====
None at present.

===== Future Scope =====
This RFC is limited to invalid integer-valued ''filter'' and ''flags'' options.


===== Voting Choices =====
Pick a title that reflects the concrete choice people will vote on. 

Please consult [[https://github.com/php/policies/blob/main/feature-proposals.rst#voting-phase|the php/policies repository]] for the current voting guidelines.

----

Primary Vote requiring a 2/3 majority to accept the RFC:

<doodle title="Implement $feature as outlined in the RFC?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====
Implementation and PHPT tests: TBD.

===== Changelog =====
* 2026-10-03: Initial RFC draft.