Value Validators

Need to quickly and easily verify that a variable contains, for example, a valid email address? Then Nette\Utils\Validators will come in handy, a static class with useful functions for validating values.

Installation:

composer require nette/utils

All examples assume the following class alias is defined:

use Nette\Utils\Validators;

Basic Usage

The Validators class provides numerous methods for checking values, such as isList(), isUnicode(), isEmail(), isUrl(), etc., for use in your code:

if (!Validators::isEmail($email)) {
	throw new InvalidArgumentException('Invalid email address provided.');
}

Furthermore, it can verify whether the value satisfies the so-called expected types, which is a string where the individual options are separated by a vertical bar |. This makes it easy to verify union types using is():

if (!Validators::is($val, 'int|string|bool')) {
	// Handle invalid type...
}

This also allows you to create systems where expectations need to be written as strings (e.g., in annotations or configurations) and then validate values against them.

You can also declare an assertion, which throws an exception if the expectation is not met.

Expected Types

Expected types form a string consisting of one or more variants separated by a pipe |, similar to how types are written in PHP (e.g., 'int|string|bool'). Nullable notation ?int is also accepted.

An array where all elements are of a certain type is written in the form int[].

Some types can be followed by a colon and a length :length or a range :[min]..[max], e.g., string:10 (a string of 10 bytes length), float:10.. (a number 10 or greater), array:..10 (an array with up to ten elements), or list:10..20 (a list with 10 to 20 elements), or a regular expression like pattern:[0-9]+.

Overview of types and rules:

Assertion

assert ($value, string $expected, string $label='variable'): void

Verifies that the value is one of the expected types separated by a pipe. If not, it throws an Nette\Utils\AssertionException. The word variable in the exception message can be replaced by the $label parameter.

Validators::assert('Nette', 'string:5'); // OK (string 'Nette' has 5 bytes)
Validators::assert('Lorem ipsum dolor sit', 'string:78');
// AssertionException: The variable expects to be string:78, string 'Lorem ipsum dolor sit' given.

assertField (array $array, string|int $key, ?string $expected=null, ?string $label=null): void

Verifies that the element with key $key in array $array is one of the expected types separated by a pipe. If not, it throws an Nette\Utils\AssertionException. The string item '%' in array in the exception message can be replaced by the $label parameter.

$arr = ['foo' => 'Nette'];

Validators::assertField($arr, 'foo', 'string:5'); // OK
Validators::assertField($arr, 'bar', 'string:15');
// AssertionException: Missing item 'bar' in array.
Validators::assertField($arr, 'foo', 'int');
// AssertionException: The item 'foo' in array expects to be int, string 'Nette' given.

Validators

is ($value, string $expected): bool

Checks if the value is one of the expected types separated by a pipe.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false (23 is outside the range 0-10)
Validators::is('Nette Framework', 'string:15');     // true, length is 15 bytes
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

isEmail (mixed $value): bool

Verifies that the value is a valid email address. It does not verify that the domain actually exists, only the syntax is verified. The function also accounts for future TLDs, which may also be in unicode.

Validators::isEmail('example@nette.org'); // true
Validators::isEmail('example@localhost'); // false
Validators::isEmail('nette');             // false

isInRange (mixed $value, array $range): bool

Checks if the value is within the given range [min, max], where the upper or lower bound can be omitted (null). Numbers, strings, and DateTime objects can be compared.

If both boundaries are missing ([null, null]) or the value is null, it returns false.

Validators::isInRange(5, [0, 5]);     // true
Validators::isInRange(23, [null, 5]); // false
Validators::isInRange(23, [5]);       // true (equivalent to [5, null])
Validators::isInRange(1, [5]);        // false

isNone (mixed $value): bool

Checks if the value is 0, '', false, null, 0.0 or [].

Validators::isNone(0); // true
Validators::isNone(''); // true
Validators::isNone(false); // true
Validators::isNone(null); // true
Validators::isNone('nette'); // false

isNumeric (mixed $value): bool

Checks if the value is a number or a number represented as a string.

Validators::isNumeric(23);      // true
Validators::isNumeric(1.78);    // true
Validators::isNumeric('+42');   // true
Validators::isNumeric('3.14');  // true
Validators::isNumeric('nette'); // false
Validators::isNumeric('1e6');   // false (scientific notation not accepted)

isNumericInt (mixed $value): bool

Checks if the value is an integer or an integer represented as a string.

Validators::isNumericInt(23);      // true
Validators::isNumericInt(1.78);    // false
Validators::isNumericInt('+42');   // true
Validators::isNumericInt('3.14');  // false
Validators::isNumericInt('nette'); // false

isPhpIdentifier (string $value): bool

Checks if the value is a syntactically valid identifier in PHP (e.g., for class names, method names, function names, etc.).

Validators::isPhpIdentifier('');        // false
Validators::isPhpIdentifier('Hello1');  // true
Validators::isPhpIdentifier('1Hello');  // false
Validators::isPhpIdentifier('one two'); // false

isBuiltinType (string $type): bool

Determines if $type is a PHP built-in type (e.g., string, int, array, bool). Otherwise, it's assumed to be a class name.

Validators::isBuiltinType('string'); // true
Validators::isBuiltinType('Foo');    // false

isTypeDeclaration (string $type): bool

Checks whether the given type declaration string is syntactically valid according to PHP's type declaration rules (including union, intersection, DNF types).

Validators::isTypeDeclaration('?string');      // true
Validators::isTypeDeclaration('string|null');  // true
Validators::isTypeDeclaration('Foo&Bar');      // true
Validators::isTypeDeclaration('(A&C)|null');   // true

Validators::isTypeDeclaration('?string|null'); // false
Validators::isTypeDeclaration('|foo');         // false
Validators::isTypeDeclaration('(A|B)');        // false

isClassKeyword (string $type): bool

Determines if $type is one of the internal type keywords self, parent, or static.

Validators::isClassKeyword('self'); // true
Validators::isClassKeyword('Foo');  // false

isUnicode (mixed $value): bool

Checks if the value is a valid UTF-8 string.

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false (invalid UTF-8 sequence)

isUrl (mixed $value): bool

Checks if the value is a valid absolute URL address according to RFC 3986.

Validators::isUrl('https://nette.org:8080/path?query#fragment'); // true
Validators::isUrl('http://localhost');            // true
Validators::isUrl('http://192.168.1.1');          // true
Validators::isUrl('http://[::1]');                // true
Validators::isUrl('http://user:pass@nette.org');  // false (userinfo part not validated by this function)
Validators::isUrl('nette.org');                   // false (missing scheme)

isUri (string $value): bool

Verifies that the value is a valid URI address, meaning it's a string starting with a syntactically valid scheme followed by a colon (e.g., http:, https:, mailto:, ftp:).

Validators::isUri('https://nette.org');           // true
Validators::isUri('mailto:gandalf@example.org');  // true
Validators::isUri('nette.org');                   // false (missing scheme)