FILTER_THROW_ON_FAILURE

The filter functions, like filter_var(), check whether a value is valid, such as an email address or an integer. When validation fails you get false back, or null with FILTER_NULL_ON_FAILURE, so you end up writing your own if to throw an exception. This RFC from Daniel Scherzer adds a FILTER_THROW_ON_FAILURE flag that makes a failed check throw for you, modeled on JSON_THROW_ON_ERROR.

Checking the return value isn't always enough, either. A filter with a callback can legitimately return false or null even when it succeeds, and an exception makes a real failure unambiguous.

Show me#

Here is a trimmed version of the RFC's example. Before:

function validateUser($email, $userId) {
	if (filter_var($email, FILTER_VALIDATE_EMAIL) === false) {
		return false;
	}
	if (filter_var($userId, FILTER_VALIDATE_INT) === false) {
		return false;
	}
	return true;
}

After:

function validateUser($email, $userId) {
	try {
		filter_var($email, FILTER_VALIDATE_EMAIL, FILTER_THROW_ON_FAILURE);
		filter_var($userId, FILTER_VALIDATE_INT, FILTER_THROW_ON_FAILURE);
		return true;
	} catch (\Filter\FilterFailedException $e) {
		return false;
	}
}

What it adds#

• A new flag, FILTER_THROW_ON_FAILURE, which you can use anywhere other filter flags go.
• A new base exception, Filter\FilterException.
• Filter\FilterFailedException, which extends it and is thrown when validation fails.

You can't combine the new flag with FILTER_NULL_ON_FAILURE. Trying to do so throws a ValueError.

What it means for existing code#

Nothing changes unless you use the new flag. The RFC adds one new global constant and two new classes in the Filter namespace, and a GitHub search by the author found no code that would clash with those names.

The vote#

It passed 18 to 1, clearing the two-thirds majority it needed. The poll offered only Yes and No, and voting closed on August 7, 2025. It was proposed for PHP 8.5, and the page marks it as implemented.