PHP: rfc:filter_throw_on_failure

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: FILTER_THROW_ON_FAILURE  ======
  * Version: 0.1
  * Date: 2025-06-21
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: Under discussion
  * Implementation: https://github.com/php/php-src/pull/18896

===== Introduction =====
The filter extension (ext/filter) can be used to verify that values (either given as variables or extracted from various superglobals like <php>$_GET</php>) match specified filters (like being a valid email address). Normally, when a value fails validation, <php>false</php> is returned (or when validating an array, <php>false</php> is used for just that array key). With the <php>FILTER_NULL_ON_FAILURE</php> flag, the result is <php>null</php> instead of false. We propose to add a new flag to have the filter extension throw exceptions on failure: <php>FILTER_THROW_ON_FAILURE</php>.

Developers that require that input match a certain filter will frequently call the filter function and then manually throw an exception if the result is <php>false</php> (or <php>null</php> with <php>FILTER_NULL_ON_FAILURE</php>). Additionally, both <php>false</php> and <php>null</php> are valid results for successful filtering, e.g. when using a callback. Thus, merely checking the return value is not always enough to know if validation succeeded or not.

This new flag is similar to <php>JSON_THROW_ON_ERROR</php> and was inspired by [[rfc:json_throw_on_error]].

===== Proposal =====
A new filter flag is added, <php>FILTER_THROW_ON_FAILURE</php>, that triggers an exception whenever a filter's validation fails.

In keeping with the recent [[rfc:extension_exceptions|RFC: Throwable Hierarchy Policy for Extensions]], a new base class <php>Filter\FilterException</php> is added, and it is extended by <php>Filter\FilterFailedException</php>, which is what gets thrown when validation fails:

<PHP>
namespace Filter {

	class FilterException extends \Exception {}

	class FilterFailedException extends FilterException {}

}
</PHP>

The flag can be used in the same places that other flags are.

The new flag cannot be combined with <php>FILTER_NULL_ON_FAILURE</php>; trying to do so will result in a <php>ValueError</php> being thrown.

==== Examples ====
Existing code written like:

<PHP>
function validateUser($email, $userId, $userName) {
	if (filter_var($email, FILTER_VALIDATE_EMAIL) === false) {
		return false;
	}
	if (filter_var($userId, FILTER_VALIDATE_INT) === false) {
		return false;
	}
	if (filter_var(
		$userName,
		FILTER_VALIDATE_REGEXP,
		['options' => ['regexp' => '/^[a-z]+$/']]
	) === false) {
		return false;
	}
	return true;
}
</PHP>

could instead be simplified to:
<PHP>
function validateUser($email, $userId, $userName) {
	try {
		filter_var($email, FILTER_VALIDATE_EMAIL, FILTER_THROW_ON_FAILURE);
		filter_var($userId, FILTER_VALIDATE_INT, FILTER_THROW_ON_FAILURE);
		filter_var(
			$userName,
			FILTER_VALIDATE_REGEXP,
			['options' => ['regexp' => '/^[a-z]+$/'], 'flags' => FILTER_THROW_ON_FAILURE]
		);
		return true;
	} catch (\Filter\FilterFailedException $e) {
		return false;
	}
}
</PHP>

reducing the duplication around checking return results.

===== Backward Incompatible Changes =====
New global constant <php>FILTER_THROW_ON_FAILURE</php> is added; 2025.07.05 GitHub search for <php>"FILTER_THROW_ON_FAILURE"</php> had no hits.

New class <php>\Filter\FilterException</php> is added; 2025.07.05 GitHub search for <php>/(class|interface|trait|enum) FilterException/ lang:php -is:fork</php> yielded 269 hits for code; from what I saw none are in a namespace named <php>Filter</php>.

New class <php>\Filter\FilterFailedException</php> is added; 2025.07.05 GitHub search for <php>/(class|interface|trait|enum) FilterFailedException/ lang:php -is:fork</php> yielded a single hit, which is in a different namespace.

===== Proposed PHP Version(s) =====
PHP 8.5

===== RFC Impact =====

==== To Existing Extensions ====
Only ext/filter is impacted.

===== Voting Choices =====
Add <php>FILTER_THROW_ON_FAILURE</php> and the associated exception classes?

<doodle title="Add FILTER_THROW_ON_FAILURE and the associated exception classes?" voteType="single" closed="true" closeon="2025-01-01T15:30:00Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====
https://github.com/php/php-src/pull/18896

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====

  - [[rfc:extension_exceptions]]
  - [[rfc:json_throw_on_error]]
  - Feature request on GitHub, https://github.com/php/php-src/issues/16710
Page Tools
