Değer Doğrulayıcıları

Bir değişkenin örneğin geçerli bir e-posta adresi içerdiğini hızlı ve kolayca doğrulamanız mı gerekiyor? O zaman değerleri doğrulamak için kullanışlı fonksiyonlar içeren statik sınıf Nette\Utils\Validators işinize yarayacak.

Kurulum:

composer require nette/utils

Tüm örnekler, aşağıdaki sınıf takma adının tanımlandığını varsayar:

use Nette\Utils\Validators;

Temel Kullanım

Validators sınıfı, kodunuzda kullanabileceğiniz pek çok değer denetleme metodu sunar: isUnicode(), isEmail(), isUrl() vb.

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

Ayrıca değerin, seçeneklerin dikey çizgi | ile ayrıldığı bir dize olan Beklenen Türlerden birine uyup uymadığını da doğrulayabilir. Bu, is() ile birleşim türlerini doğrulamayı kolaylaştırır:

if (!Validators::is($val, 'int|string|bool')) {
	// Geçersiz türü ele al...
}

Bu, beklentilerin dize olarak yazılması gereken (örneğin açıklamalarda veya yapılandırmalarda) ve değerlerin bunlara göre doğrulandığı sistemler kurmanıza da olanak tanır.

Beklenti karşılanmadığında istisna fırlatan bir doğrulama iddiası da tanımlayabilirsiniz.

Beklenen Türler

Beklenen türler, PHP'de türlerin yazılışına benzer şekilde dikey çizgi | ile ayrılmış bir ya da daha fazla seçenekten oluşan bir dizedir (örneğin 'int|string|bool'). Nullable yazımı ?int de kabul edilir.

Tüm öğeleri belirli bir türde olan bir dizi int[] biçiminde yazılır.

Bazı türlerin ardına iki nokta üst üste ile bir uzunluk :uzunluk ya da bir aralık :[min]..[max] gelebilir; örneğin string:10 (10 bayt uzunluğunda bir dize), float:10.. (10 veya daha büyük bir sayı), array:..10 (en fazla on öğeli bir dizi) ya da list:10..20 (10 ile 20 arası öğeli bir liste); ayrıca pattern:[0-9]+ gibi bir düzenli ifade de yazılabilir.

Türlerin ve kuralların özeti:

Doğrulama İddiası

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

Değerin, dikey çizgiyle ayrılmış Beklenen Türlerden biri olduğunu doğrular. Değilse Nette\Utils\AssertionException fırlatır. İstisna mesajındaki variable sözcüğü $label parametresiyle değiştirilebilir.

Validators::assert('Nette', 'string:5'); // OK ('Nette' dizesi 5 bayt)
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 dizisindeki $key anahtarlı öğenin, dikey çizgiyle ayrılmış Beklenen Türlerden biri olduğunu doğrular. Değilse Nette\Utils\AssertionException fırlatır. İstisna mesajındaki item '%' in array dizesi $label parametresiyle değiştirilebilir.

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

Doğrulayıcılar

is ($value, string $expected): bool

Değerin, dikey çizgiyle ayrılmış Beklenen Türlerden biri olup olmadığını denetler.

Validators::is(1, 'int|float');  // true
Validators::is(23, 'int:0..10'); // false (23, 0-10 aralığının dışında)
Validators::is('Nette Framework', 'string:15');     // true, uzunluk 15 bayt
Validators::is('Nette Framework', 'string:8..');    // true
Validators::is('Nette Framework', 'string:30..40'); // false

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

Iterable içindeki her değerin, dikey çizgiyle ayrılmış Beklenen Türlerden biri olup olmadığını denetler. Her öğeye uygulanan is() gibi çalışır.

$list = ['Nette', 'Framework', 2020];
Validators::everyIs($list, 'string');     // false (2020 bir dize değil)
Validators::everyIs($list, 'string|int'); // true

isEmail (string $value): bool

Değerin geçerli bir e-posta adresi olduğunu doğrular. Alan adının gerçekten var olup olmadığını denetlemez, yalnızca söz dizimini doğrular. Fonksiyon, unicode da olabilen gelecekteki TLD'leri de hesaba katar.

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

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

Değerin verilen [min, max] aralığında olup olmadığını denetler; üst ya da alt sınır atlanabilir (null). Sayılar, dizeler ve DateTime nesneleri karşılaştırılabilir.

Her iki sınır da eksikse ([null, null]) ya da değer null ise false döndürür.

Validators::isInRange(5, [0, 5]);     // true
Validators::isInRange(23, [null, 5]); // false
Validators::isInRange(23, [5]);       // true ([5, null] ile eşdeğer)
Validators::isInRange(1, [5]);        // false

isNone (mixed $value): bool

Değerin 0, '', false, null, 0.0 ya da [] olup olmadığını denetler.

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

isNumeric (mixed $value): bool

Değerin bir sayı ya da dize olarak gösterilmiş bir sayı olup olmadığını denetler.

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 (bilimsel gösterim kabul edilmez)

isNumericInt (mixed $value): bool

Değerin bir tam sayı ya da dize olarak gösterilmiş bir tam sayı olup olmadığını denetler.

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

Değerin PHP'de söz dizimi açısından geçerli bir tanımlayıcı (örneğin sınıf, metot ya da fonksiyon adı) olup olmadığını denetler.

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

isBuiltinType (string $type): bool

$type değerinin PHP'nin yerleşik türlerinden biri (örneğin string, int, array, bool) olup olmadığını belirler. Değilse sınıf adı sayılır.

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

isTypeDeclaration (string $type): bool

Verilen tür bildirimi dizesinin, PHP'nin tür bildirimi kurallarına göre (birleşim, kesişim ve DNF türleri dahil) söz dizimi açısından geçerli olup olmadığını denetler.

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 değerinin self, parent ya da static iç tür anahtar sözcüklerinden biri olup olmadığını belirler.

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

isUnicode (mixed $value): bool

Değerin geçerli bir UTF-8 dizesi olup olmadığını denetler.

Validators::isUnicode('nette'); // true
Validators::isUnicode('');      // true
Validators::isUnicode("\xA0");  // false (geçersiz UTF-8 dizisi)

isUrl (string $value): bool

Değerin RFC 3986'ya göre geçerli bir mutlak URL adresi olup olmadığını denetler.

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 kısmı bu fonksiyonla doğrulanmaz)
Validators::isUrl('nette.org');                   // false (şema eksik)

isUri (string $value): bool

Değerin geçerli bir URI adresi olduğunu, yani söz dizimi açısından geçerli bir şema ile başlayıp ardından iki nokta üst üste gelen bir dize olduğunu doğrular (örneğin http:, https:, mailto:, ftp:).

Validators::isUri('https://nette.org');           // true
Validators::isUri('mailto:gandalf@example.org');  // true
Validators::isUri('nette.org');                   // false (şema eksik)