====== PHP RFC: Add Filter\Filter and Filter\Flag Enums ======
  * Version: 0.9
  * Date: 2026-10-03
  * Author: Muhammed Arshid, arshidkv12@gmail.com
  * Status: Voting
  * Implementation: https://github.com/php/php-src/pull/24111
  * Discussion thread: https://news-web.php.net/php.internals/132813
  * Voting thread: https://news-web.php.net/php.internals/132882


===== Introduction =====
The Filter extension currently exposes filter IDs and filter flags primarily as integer constants such as ''FILTER_VALIDATE_INT'' and ''FILTER_FLAG_ALLOW_HEX''.

These constants remain widely used and will continue to be supported. However, using integers for filter IDs and flags provides little type information and makes the API less discoverable when using modern PHP type systems.

This RFC proposes adding two backed enums:

  * ''Filter\Filter'' for filter IDs.
  * ''Filter\Flag'' for filter flags.

The enums provide a typed and discoverable alternative while preserving the existing integer constants and APIs.


===== Proposal =====
Add the following two backed enums:

<PHP>
namespace Filter;
enum Filter: int
{
  case DEFAULT = FILTER_DEFAULT;
  
  case VALIDATE_BOOL = FILTER_VALIDATE_BOOL;
  case VALIDATE_INT = FILTER_VALIDATE_INT;
  case VALIDATE_FLOAT = FILTER_VALIDATE_FLOAT;
  case VALIDATE_REGEXP = FILTER_VALIDATE_REGEXP;
  case VALIDATE_DOMAIN = FILTER_VALIDATE_DOMAIN;
  case VALIDATE_URL = FILTER_VALIDATE_URL;
  case VALIDATE_EMAIL = FILTER_VALIDATE_EMAIL;
  case VALIDATE_IP = FILTER_VALIDATE_IP;
  case VALIDATE_MAC = FILTER_VALIDATE_MAC;
  
  case SANITIZE_STRING = FILTER_SANITIZE_STRING;
  case SANITIZE_EMAIL = FILTER_SANITIZE_EMAIL;
  case SANITIZE_URL = FILTER_SANITIZE_URL;
  case SANITIZE_NUMBER_INT = FILTER_SANITIZE_NUMBER_INT;
  case SANITIZE_NUMBER_FLOAT = FILTER_SANITIZE_NUMBER_FLOAT;
  case SANITIZE_SPECIAL_CHARS = FILTER_SANITIZE_SPECIAL_CHARS;
  case SANITIZE_FULL_SPECIAL_CHARS = FILTER_SANITIZE_FULL_SPECIAL_CHARS;
  case SANITIZE_ADD_SLASHES = FILTER_SANITIZE_ADD_SLASHES;
  
  case CALLBACK = FILTER_CALLBACK;
}


enum Flag: int
{
  case NONE = FILTER_FLAG_NONE;
  
  case ALLOW_OCTAL = FILTER_FLAG_ALLOW_OCTAL;
  case ALLOW_HEX = FILTER_FLAG_ALLOW_HEX;
  
  case STRIP_LOW = FILTER_FLAG_STRIP_LOW;
  case STRIP_HIGH = FILTER_FLAG_STRIP_HIGH;
  case STRIP_BACKTICK = FILTER_FLAG_STRIP_BACKTICK;
  
  case ENCODE_LOW = FILTER_FLAG_ENCODE_LOW;
  case ENCODE_HIGH = FILTER_FLAG_ENCODE_HIGH;
  case ENCODE_AMP = FILTER_FLAG_ENCODE_AMP;
  case NO_ENCODE_QUOTES = FILTER_FLAG_NO_ENCODE_QUOTES;
  case EMPTY_STRING_NULL = FILTER_FLAG_EMPTY_STRING_NULL;
  
  case ALLOW_FRACTION = FILTER_FLAG_ALLOW_FRACTION;
  case ALLOW_THOUSAND = FILTER_FLAG_ALLOW_THOUSAND;
  case ALLOW_SCIENTIFIC = FILTER_FLAG_ALLOW_SCIENTIFIC;
  
  case PATH_REQUIRED = FILTER_FLAG_PATH_REQUIRED;
  case QUERY_REQUIRED = FILTER_FLAG_QUERY_REQUIRED;
  
  case IPV4 = FILTER_FLAG_IPV4;
  case IPV6 = FILTER_FLAG_IPV6;
  case NO_RES_RANGE = FILTER_FLAG_NO_RES_RANGE;
  case NO_PRIV_RANGE = FILTER_FLAG_NO_PRIV_RANGE;
  case GLOBAL_RANGE = FILTER_FLAG_GLOBAL_RANGE;
}
</PHP>
The enums are backed by int, matching the existing representation of Filter IDs and flags.


===== API Changes =====

The four Filter functions will accept the new ''Filter\Filter'' and ''Filter\Flag'' enums in addition to the existing integer values.

==== filter_var() ====

A filter can be specified using ''Filter\Filter'':

<PHP>
filter_var('123', Filter\Filter::VALIDATE_INT);
</PHP>

A flag can be specified using ''Filter\Flag'':

<PHP>
filter_var(
    '123',
    Filter\Filter::VALIDATE_INT,
    Filter\Flag::ALLOW_OCTAL
);
</PHP>

Multiple flags can be combined using their backing integer values:

<PHP>
filter_var(
    '123',
    Filter\Filter::VALIDATE_INT,
    Filter\Flag::ALLOW_OCTAL->value | Filter\Flag::ALLOW_HEX->value
);
</PHP>

The existing integer API remains valid:

<PHP>
filter_var('123', FILTER_VALIDATE_INT);
</PHP>

==== filter_var_array() ==== 

A filter can be specified directly as an enum:

<PHP>
filter_var_array(
    ['id' => '123'],
    Filter\Filter::VALIDATE_INT
);
</PHP>

A filter definition can also use a ''Filter\Filter'' enum and a ''Filter\Flag'' enum:

<PHP>
filter_var_array(
    ['id' => '123'],
    [
        'id' => [
            'filter' => Filter\Filter::VALIDATE_INT,
            'flags' => Filter\Flag::ALLOW_OCTAL,
        ],
    ]
);
</PHP>

The existing integer constants remain supported:

<PHP>
filter_var_array(
    ['id' => '123'],
    [
        'id' => [
            'filter' => FILTER_VALIDATE_INT,
            'flags' => FILTER_FLAG_ALLOW_OCTAL,
        ],
    ]
);
</PHP>

==== filter_input() ==== 

A filter can be specified using ''Filter\Filter'':

<PHP>
filter_input(
    INPUT_GET,
    'id',
    Filter\Filter::VALIDATE_INT
);
</PHP>

A ''Filter\Flag'' can be supplied as the options argument:

<PHP>
filter_input(
    INPUT_GET,
    'id',
    Filter\Filter::VALIDATE_INT,
    Filter\Flag::ALLOW_OCTAL
);
</PHP>

The existing integer constants continue to work:

<PHP>
filter_input(
    INPUT_GET,
    'id',
    FILTER_VALIDATE_INT,
    FILTER_FLAG_ALLOW_OCTAL
);
</PHP>

==== ''filter_input_array()'' ====

A filter can be specified directly as an enum:

<PHP>
filter_input_array(
    INPUT_GET,
    Filter\Filter::VALIDATE_INT
);
</PHP>

A filter definition can use both enums:

<PHP>
filter_input_array(
    INPUT_GET,
    [
        'id' => [
            'filter' => Filter\Filter::VALIDATE_INT,
            'flags' => Filter\Flag::ALLOW_OCTAL,
        ],
    ]
);
</PHP>

The existing constants remain supported:

<PHP>
filter_input_array(
    INPUT_GET,
    [
        'id' => [
            'filter' => FILTER_VALIDATE_INT,
            'flags' => FILTER_FLAG_ALLOW_OCTAL,
        ],
    ]
);
</PHP>

These examples demonstrate that the enums provide a typed alternative to the existing integer constants without requiring existing applications to change their code.



===== Backward Incompatible Changes =====
This RFC does **not** remove or change the existing Filter constants.

Existing code continues to work:

<PHP>
filter_var('123', FILTER_VALIDATE_INT);
</PHP>

and:

<PHP>
filter_var(
    '0xff',
    FILTER_VALIDATE_INT,
    FILTER_FLAG_ALLOW_HEX
);
</PHP>

Integer arguments remain accepted by all affected APIs.

The enums provide an additional way to specify filters and flags.

===== Proposed PHP Version(s) =====
PHP 8.7

===== 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 =====
Voting ends on 2026-11-04 at 00:00:00 UTC.

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

<doodle title="Implement Filter\Filter and Filter\Flag enums as outlined in the RFC?" voteType="single" closed="false" closeon="2026-11-04T00:00:00Z">
   * Yes
   * No
   * Abstain
</doodle>


===== Patches and Tests =====
Implementation and tests: https://github.com/php/php-src/pull/24111

===== Changelog =====
  * 2026-10-07: Revised RFC to reflect the enum implementation in php-src PR #24111.
  * 2026-10-03: Initial RFC draft.