値のバリデータ
変数が有効なメールアドレスを含んでいるかどうかなどを、素早く簡単に確かめたいですか。そんなときに役立つのが 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]+ のような正規表現です。
型と規則の一覧:
| PHP の型 | ||||
|---|---|---|---|---|
array |
要素数の範囲を指定できます | |||
bool |
||||
boolean |
bool の別名 |
|||
float |
値の範囲を指定できます | |||
int |
値の範囲を指定できます | |||
integer |
int の別名 |
|||
null |
||||
object |
||||
resource |
||||
scalar |
`int | float | bool | string` |
string |
バイト単位の長さの範囲を指定できます | |||
callable |
||||
iterable |
||||
mixed |
||||
| 疑似型 | ||||
list |
添字配列。要素数の範囲を指定できます | |||
none |
空の値: ''、null、false、0、0.0、[] |
|||
number |
`int | float` | ||
numeric |
文字列表現も含む数 | |||
numericint |
文字列表現も含む整数 | |||
unicode |
UTF-8 の文字列。文字数の範囲を指定できます | |||
| 文字クラス（空文字列であってはいけません） | ||||
alnum |
すべての文字が英数字 | |||
alpha |
すべての文字が英字 [A-Za-z] |
|||
digit |
すべての文字が数字 | |||
lower |
すべての文字が小文字 [a-z] |
|||
space |
すべての文字が空白 | |||
upper |
すべての文字が大文字 [A-Z] |
|||
xdigit |
すべての文字が 16 進数字 [0-9A-Fa-f] |
|||
| 構文の検証 | ||||
pattern |
文字列全体が一致しなければならない正規表現 | |||
email |
メール | |||
identifier |
PHP の識別子 | |||
url |
URL | |||
uri |
URI | |||
| 環境の検証 | ||||
class |
存在するクラス名である | |||
interface |
存在するインターフェース名である | |||
directory |
存在するディレクトリのパスである | |||
file |
存在するファイルのパスである | |||
アサーション
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（スキームがない）