Değer Doğrulayıcıları
*********************

.[perex]
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 [api:Nette\Utils\Validators] işinize yarayacak.


Kurulum:

```shell
composer require nette/utils
```

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

```php
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.

```php
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ürler]den birine uyup uymadığını da doğrulayabilir. Bu, [#is()] ile birleşim türlerini doğrulamayı kolaylaştırır:

```php
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ı |#assert()] 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:

.[wide]
| PHP türleri  ||
|--------------------------
| `array` .{width: 140px} | öğe sayısı için aralık belirtilebilir
| `bool`     |
| `boolean`  | `bool` için takma ad
| `float`    | değer için aralık belirtilebilir
| `int`      | değer için aralık belirtilebilir
| `integer`  | `int` için takma ad
| `null`     |
| `object`   |
| `resource` |
| `scalar`   | `int|float|bool|string`
| `string`   | bayt cinsinden uzunluk için aralık belirtilebilir
| `callable` |
| `iterable` |
| `mixed`    |
|------------------------------------------------
| Sözde türler  ||
|------------------------------------------------
| `list`      | indeksli dizi, öğe sayısı için aralık belirtilebilir
| `none`      | boş değer: `''`, `null`, `false`, `0`, `0.0`, `[]`
| `number`    | `int|float`
| `numeric`   | [dize gösterimi dahil sayı |#isNumeric()]
| `numericint`| [dize gösterimi dahil tam sayı |#isNumericInt()]
| `unicode`   | [UTF-8 dizesi |#isUnicode()], karakter cinsinden uzunluk için aralık belirtilebilir
|------------------------------------------------
| Karakter sınıfı (boş dize olmamalı) ||
|------------------------------------------------
| `alnum`  | tüm karakterler alfanümerik
| `alpha`  | tüm karakterler harf `[A-Za-z]`
| `digit`  | tüm karakterler rakam
| `lower`  | tüm karakterler küçük harf `[a-z]`
| `space`  | tüm karakterler boşluk
| `upper`  | tüm karakterler büyük harf `[A-Z]`
| `xdigit` | tüm karakterler onaltılık rakam `[0-9A-Fa-f]`
|------------------------------------------------
| Söz dizimi doğrulaması  ||
|------------------------------------------------
| `pattern`   | dizenin **tamamının** eşleşmesi gereken düzenli ifade
| `email`     | [E-posta |#isEmail()]
| `identifier`| [PHP tanımlayıcısı |#isPhpIdentifier()]
| `url`       | [URL |#isUrl()]
| `uri`       | [URI |#isUri()]
|------------------------------------------------
| Ortam doğrulaması  ||
|------------------------------------------------
| `class`     | var olan bir sınıf adı
| `interface` | var olan bir arayüz adı
| `directory` | var olan bir dizin yolu
| `file`      | var olan bir dosya yolu


Doğrulama İddiası
=================


assert($value, string $expected, string $label='variable'): void .[method]
--------------------------------------------------------------------------

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

```php
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 .[method]
---------------------------------------------------------------------------------------------------------------------

`$array` dizisindeki `$key` anahtarlı öğenin, dikey çizgiyle ayrılmış [#Beklenen Türler]den biri olduğunu doğrular. Değilse [api:Nette\Utils\AssertionException] fırlatır. İstisna mesajındaki `item '%' in array` dizesi `$label` parametresiyle değiştirilebilir.

```php
$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 .[method]
--------------------------------------------

Değerin, dikey çizgiyle ayrılmış [#Beklenen Türler]den biri olup olmadığını denetler.

```php
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 .[method]
-----------------------------------------------------------

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

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


isEmail(string $value): bool .[method]
--------------------------------------

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|https://tr.wikipedia.org/wiki/Üst_düzey_alan_adı] de hesaba katar.

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


isInRange(mixed $value, array $range): bool .[method]
-----------------------------------------------------

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.

```php
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 .[method]
------------------------------------

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

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


isNumeric(mixed $value): bool .[method]
---------------------------------------

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

```php
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 .[method]
------------------------------------------

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

```php
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 .[method]
----------------------------------------------

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.

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


isBuiltinType(string $type): bool .[method]
-------------------------------------------

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

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


isTypeDeclaration(string $type): bool .[method]
-----------------------------------------------

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.

```php
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 .[method]
--------------------------------------------

`$name` değerinin `self`, `parent` ya da `static` iç tür anahtar sözcüklerinden biri olup olmadığını belirler.

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


isUnicode(mixed $value): bool .[method]
---------------------------------------

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

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


isUrl(string $value): bool .[method]
------------------------------------

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

```php
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 .[method]
------------------------------------

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:`).

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