値のバリデータ

変数が有効なメールアドレスを含んでいるかどうかなどを、素早く簡単に確かめたいですか。そんなときに役立つのが Nette\Utils\Validators です。値を検証する便利な関数を集めた静的クラスです。

インストール:

composer require nette/utils

以下の例では、次のクラスの別名が定義されているものとします。

use Nette\Utils\Validators;

基本的な使い方

Validators クラスは、コードの中で使える値のチェック用メソッドを数多く提供します。isUnicode()、isEmail()、isUrl()などです。

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

さらに、値がいわゆる期待される型を満たすかも確かめられます。期待される型は、個々の選択肢を縦棒 | で区切った文字列です。おかげで is()を使って合併型を簡単に検証できます。

if (!Validators::is($val, 'int|string|bool')) {
	// 型が正しくない場合の処理...
}

これにより、期待を文字列で書く必要のあるシステム（アノテーションや設定など）を作り、それに対して値を検証できます。

アサーションを宣言することもでき、期待が満たされない場合には例外を投げます。

期待される型

期待される型は、PHP での型の書き方と同じように、パイプ | で区切られたひとつ以上の候補から成る文字列です（'int|string|bool' など）。nullable の書き方 ?int も受け付けます。

すべての要素がある型である配列は int[] の形で書きます。

一部の型のあとにはコロンと長さ :length や範囲 :[min]..[max] を続けられます。たとえば string:10（長さ 10 バイトの文字列）、float:10..（10 以上の数）、array:..10（要素が 10 個までの配列）、list:10..20（要素が 10 から 20 個のリスト）、あるいは pattern:[0-9]+ のような正規表現です。

型と規則の一覧:

アサーション

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

値がパイプで区切られた期待される型のいずれかであることを確かめます。そうでなければ Nette\Utils\AssertionException を投げます。例外のメッセージ中の variable という語は $label パラメータで置き換えられます。

Validators::assert('Nette', 'string:5'); // OK（文字列 'Nette' は 5 バイト）
Validators::assert('Lorem ipsum dolor sit', 'string:78');
// AssertionException: The variable expects to be string in range 78, string 'Lorem ipsum dolor sit' given.

assertField (array $array, string|int $key, ?string $expected=null, string $label="item '%' in array"): void

配列 $array のキー $key の要素が、パイプで区切られた期待される型のいずれかであることを確かめます。そうでなければ Nette\Utils\AssertionException を投げます。例外のメッセージ中の item '%' in array という文字列は $label パラメータで置き換えられます。

$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.

バリデータ

is ($value, string $expected): bool

値がパイプで区切られた期待される型のいずれかかを調べます。

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false（23 は 0〜10 の範囲外）
Validators::is('Nette Framework', 'string:15');     // true、長さは 15 バイト
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

everyIs (iterable $values, string $expected): bool

反復可能なものの中のすべての値が、パイプで区切られた期待される型のいずれかかを調べます。各要素に is()を適用するのと同じように働きます。

$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string');     // false（2020 は文字列ではない）
Validators::everyIs($list, 'string|int'); // true

isEmail (string $value): bool

値が有効なメールアドレスかを確かめます。ドメインが実際に存在するかは確かめず、構文だけを検証します。この関数は将来の TLD（Unicode のものも含みます）も考慮します。

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

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

値が指定した範囲 [min, max] の中にあるかを調べます。上限や下限は省略できます（null）。数値、文字列、DateTime のオブジェクトを比較できます。

両方の境界がない場合（[null, null]）や値が null の場合は false を返します。

Validators::isInRange(5, [0, 5]);     // true
Validators::isInRange(23, [null, 5]); // false
Validators::isInRange(23, [5]);       // true（[5, null] と同じ）
Validators::isInRange(1, [5]);        // false

isNone (mixed $value): bool

値が 0、''、false、null、0.0、[] のいずれかかを調べます。

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

isNumeric (mixed $value): bool

値が数、または数を表す文字列かを調べます。

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（指数表記は受け付けません）

isNumericInt (mixed $value): bool

値が整数、または整数を表す文字列かを調べます。

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

値が PHP の構文として正しい識別子（クラス名、メソッド名、関数名などに使えるもの）かを調べます。

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

isBuiltinType (string $type): bool

$type が PHP の組み込み型（string、int、array、bool など）かを判定します。そうでなければクラス名とみなされます。

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

isTypeDeclaration (string $type): bool

与えられた型宣言の文字列が、PHP の型宣言の規則（合併型、交差型、DNF 型を含みます）に照らして構文的に正しいかを調べます。

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 $name): bool

$name が内部の型キーワード self、parent、static のいずれかかを判定します。

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

isUnicode (mixed $value): bool

値が正しい UTF-8 の文字列かを調べます。

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false（不正な UTF-8 の並び）

isUrl (string $value): bool

値が RFC 3986 に従った正しい絶対 URL かを調べます。

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 の部分を検証しません）
Validators::isUrl('nette.org');                   // false（スキームがない）

isUri (string $value): bool

値が正しい URI かを確かめます。つまり、構文として正しいスキームにコロンが続く文字列（http:、https:、mailto:、ftp: など）であることを確かめます。

Validators::isUri('https://nette.org');           // true
Validators::isUri('mailto:gandalf@example.org');  // true
Validators::isUri('nette.org');                   // false（スキームがない）