Add Filter\Filter and Filter\Flag Enums View as Markdown

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:

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;
}

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:

filter_var('123', Filter\Filter::VALIDATE_INT);

A flag can be specified using Filter\Flag:

filter_var(
    '123',
    Filter\Filter::VALIDATE_INT,
    Filter\Flag::ALLOW_OCTAL
);

Multiple flags can be combined using their backing integer values:

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

The existing integer API remains valid:

filter_var('123', FILTER_VALIDATE_INT);

filter_var_array()

A filter can be specified directly as an enum:

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

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

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

The existing integer constants remain supported:

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

filter_input()

A filter can be specified using Filter\Filter:

filter_input(
    INPUT_GET,
    'id',
    Filter\Filter::VALIDATE_INT
);

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

filter_input(
    INPUT_GET,
    'id',
    Filter\Filter::VALIDATE_INT,
    Filter\Flag::ALLOW_OCTAL
);

The existing integer constants continue to work:

filter_input(
    INPUT_GET,
    'id',
    FILTER_VALIDATE_INT,
    FILTER_FLAG_ALLOW_OCTAL
);

''filter_input_array()''

A filter can be specified directly as an enum:

filter_input_array(
    INPUT_GET,
    Filter\Filter::VALIDATE_INT
);

A filter definition can use both enums:

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

The existing constants remain supported:

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

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:

filter_var('123', FILTER_VALIDATE_INT);

and:

filter_var(
    '0xff',
    FILTER_VALIDATE_INT,
    FILTER_FLAG_ALLOW_HEX
);

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

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

Vote: Implement Filter\Filter and Filter\Flag enums as outlined in the RFC? — Yes: 0 · No: 0 · Abstain: 0 (closed)

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.