Σχήμα: Επικύρωση δεδομένων
**************************

.[perex]
Μια πρακτική βιβλιοθήκη για την επικύρωση και την κανονικοποίηση δομών δεδομένων έναντι ενός δεδομένου σχήματος με ένα έξυπνο και κατανοητό API.

Εγκατάσταση:

```shell
composer require nette/schema
```


Βασική χρήση .[#toc-basic-usage]
--------------------------------

Στη μεταβλητή `$schema` έχουμε ένα σχήμα επικύρωσης (τι ακριβώς σημαίνει αυτό και πώς να το δημιουργήσουμε θα πούμε αργότερα) και στη μεταβλητή `$data` έχουμε μια δομή δεδομένων που θέλουμε να επικυρώσουμε και να κανονικοποιήσουμε. Αυτό μπορεί να είναι, για παράδειγμα, δεδομένα που αποστέλλονται από τον χρήστη μέσω ενός API, ενός αρχείου ρυθμίσεων κ.λπ.

Το έργο αναλαμβάνει η κλάση [api:Nette\Schema\Processor], η οποία επεξεργάζεται την είσοδο και είτε επιστρέφει κανονικοποιημένα δεδομένα είτε πετάει μια εξαίρεση [api:Nette\Schema\ValidationException] σε περίπτωση σφάλματος.

```php
$processor = new Nette\Schema\Processor;

try {
	$normalized = $processor->process($schema, $data);
} catch (Nette\Schema\ValidationException $e) {
	echo 'Data is invalid: ' . $e->getMessage();
}
```

Η μέθοδος `$e->getMessages()` επιστρέφει πίνακα όλων των συμβολοσειρών μηνυμάτων και η `$e->getMessageObjects()` επιστρέφει όλα τα μηνύματα ως αντικείμενα "Nette\Schema\Message":https://api.nette.org/schema/master/Nette/Schema/Message.html.


Ορισμός σχήματος .[#toc-defining-schema]
----------------------------------------

Και τώρα ας δημιουργήσουμε ένα σχήμα. Η κλάση [api:Nette\Schema\Expect] χρησιμοποιείται για τον ορισμό του, ουσιαστικά ορίζουμε τις προσδοκίες για το πώς θα πρέπει να μοιάζουν τα δεδομένα. Ας πούμε ότι τα δεδομένα εισόδου πρέπει να είναι μια δομή (π.χ. ένας πίνακας) που περιέχει στοιχεία `processRefund` τύπου bool και `refundAmount` τύπου int.

```php
use Nette\Schema\Expect;

$schema = Expect::structure([
	'processRefund' => Expect::bool(),
	'refundAmount' => Expect::int(),
]);
```

Πιστεύουμε ότι ο ορισμός του σχήματος φαίνεται σαφής, ακόμη και αν τον βλέπετε για πρώτη φορά.

Ας στείλουμε τα ακόλουθα δεδομένα για επικύρωση:

```php
$data = [
	'processRefund' => true,
	'refundAmount' => 17,
];

$normalized = $processor->process($schema, $data); // Εντάξει, περνάει
```

Η έξοδος, δηλαδή η τιμή `$normalized`, είναι το αντικείμενο `stdClass`. Εάν θέλουμε η έξοδος να είναι ένας πίνακας, προσθέτουμε ένα cast στο schema `Expect::structure([...])->castTo('array')`.

Όλα τα στοιχεία της δομής είναι προαιρετικά και έχουν προεπιλεγμένη τιμή `null`. Παράδειγμα:

```php
$data = [
	'refundAmount' => 17,
];

$normalized = $processor->process($schema, $data); // Εντάξει, περνάει
// $normalized = {'processRefund' => null, 'refundAmount' => 17}
```

Το γεγονός ότι η προεπιλεγμένη τιμή είναι `null` δεν σημαίνει ότι θα γινόταν δεκτή στα δεδομένα εισόδου `'processRefund' => null`. Όχι, η είσοδος πρέπει να είναι boolean, δηλαδή μόνο `true` ή `false`. Θα πρέπει να επιτρέψουμε ρητά το `null` μέσω του `Expect::bool()->nullable()`.

Ένα στοιχείο μπορεί να καταστεί υποχρεωτικό χρησιμοποιώντας το `Expect::bool()->required()`. Αλλάζουμε την προεπιλεγμένη τιμή σε `false` χρησιμοποιώντας το `Expect::bool()->default(false)` ή σύντομα χρησιμοποιώντας το `Expect::bool(false)`.

Και τι θα γινόταν αν θέλαμε να δεχτούμε το `1` and `0` εκτός από booleans; Τότε απαριθμούμε τις επιτρεπόμενες τιμές, τις οποίες επίσης θα κανονικοποιήσουμε σε boolean:

```php
$schema = Expect::structure([
	'processRefund' => Expect::anyOf(true, false, 1, 0)->castTo('bool'),
	'refundAmount' => Expect::int(),
]);

$normalized = $processor->process($schema, $data);
is_bool($normalized->processRefund); // true
```

Τώρα γνωρίζετε τα βασικά για το πώς ορίζεται το σχήμα και πώς συμπεριφέρονται τα επιμέρους στοιχεία της δομής. Τώρα θα δείξουμε ποια είναι όλα τα άλλα στοιχεία που μπορούν να χρησιμοποιηθούν στον ορισμό ενός σχήματος.


Τύποι δεδομένων: type() .[#toc-data-types-type]
-----------------------------------------------

Όλοι οι τυποποιημένοι τύποι δεδομένων PHP μπορούν να αναφερθούν στο σχήμα:

```php
Expect::string($default = null)
Expect::int($default = null)
Expect::float($default = null)
Expect::bool($default = null)
Expect::null()
Expect::array($default = [])
```

Και στη συνέχεια όλοι οι τύποι που [υποστηρίζονται από τους επικυρωτές |utils:validators#Expected Types] μέσω του `Expect::type('scalar')` ή της συντομογραφίας `Expect::scalar()`. Επίσης, γίνονται δεκτά ονόματα κλάσεων ή διεπαφών, π.χ. `Expect::type('AddressEntity')`.

Μπορείτε επίσης να χρησιμοποιήσετε τον συμβολισμό της ένωσης:

```php
Expect::type('bool|string|array')
```

Η προεπιλεγμένη τιμή είναι πάντα `null` εκτός από τις περιπτώσεις `array` και `list`, όπου είναι ένας άδειος πίνακας. (Μια λίστα είναι ένας πίνακας με ευρετηρίαση σε αύξουσα σειρά αριθμητικών κλειδιών από το μηδέν, δηλαδή ένας μη συσχετιστικός πίνακας).


Πίνακας τιμών: arrayOf() listOf() .[#toc-array-of-values-arrayof-listof]
------------------------------------------------------------------------

Ο πίνακας είναι πολύ γενική δομή, είναι πιο χρήσιμο να καθορίσετε ακριβώς ποια στοιχεία μπορεί να περιέχει. Για παράδειγμα, ένας πίνακας του οποίου τα στοιχεία μπορούν να είναι μόνο συμβολοσειρές:

```php
$schema = Expect::arrayOf('string');

$processor->process($schema, ['hello', 'world']); // OK
$processor->process($schema, ['a' => 'hello', 'b' => 'world']); // OK
$processor->process($schema, ['key' => 123]); // ΣΦΑΛΜΑ: Το 123 δεν είναι συμβολοσειρά
```

Η δεύτερη παράμετρος μπορεί να χρησιμοποιηθεί για τον προσδιορισμό των κλειδιών (από την έκδοση 1.2):

```php
$schema = Expect::arrayOf('string', 'int');

$processor->process($schema, ['hello', 'world']); // OK
$processor->process($schema, ['a' => 'hello']); // ΣΦΑΛΜΑ: 'a' δεν είναι int
```

Η λίστα είναι ένας δεικτοδοτημένος πίνακας:

```php
$schema = Expect::listOf('string');

$processor->process($schema, ['a', 'b']); // OK
$processor->process($schema, ['a', 123]); // ΣΦΑΛΜΑ: Το 123 δεν είναι συμβολοσειρά
$processor->process($schema, ['key' => 'a']); // ΣΦΑΛΜΑ: δεν είναι λίστα
$processor->process($schema, [1 => 'a', 0 => 'b']); // ΣΦΑΛΜΑ: δεν είναι λίστα
```

Η παράμετρος μπορεί επίσης να είναι ένα σχήμα, οπότε μπορούμε να γράψουμε:

```php
Expect::arrayOf(Expect::bool())
```

Η προεπιλεγμένη τιμή είναι ένας άδειος πίνακας. Εάν καθορίσετε την προεπιλεγμένη τιμή, θα συγχωνευτεί με τα δεδομένα που έχουν περάσει. Αυτό μπορεί να απενεργοποιηθεί χρησιμοποιώντας το `mergeDefaults(false)` (από την έκδοση 1.1).


Απαρίθμηση: anyOf() .[#toc-enumeration-anyof]
---------------------------------------------

`anyOf()` είναι ένα σύνολο τιμών ή σχημάτων που μπορεί να είναι μια τιμή. Εδώ είναι πώς να γράψετε έναν πίνακα στοιχείων που μπορεί να είναι είτε `'a'`, `true`, είτε `null`:

```php
$schema = Expect::listOf(
	Expect::anyOf('a', true, null),
);

$processor->process($schema, ['a', true, null, 'a']); // OK
$processor->process($schema, ['a', false]); // ΣΦΑΛΜΑ: το false δεν ανήκει εκεί
```

Τα στοιχεία της απαρίθμησης μπορούν επίσης να είναι σχήματα:

```php
$schema = Expect::listOf(
	Expect::anyOf(Expect::string(), true, null),
);

$processor->process($schema, ['foo', true, null, 'bar']); // OK
$processor->process($schema, [123]); // ΣΦΑΛΜΑ
```

Η μέθοδος `anyOf()` δέχεται παραλλαγές ως μεμονωμένες παραμέτρους, όχι ως πίνακα. Για να της παραδώσετε έναν πίνακα τιμών, χρησιμοποιήστε τον τελεστή αποσυμπίεσης `anyOf(...$variants)`.

Η προεπιλεγμένη τιμή είναι `null`. Χρησιμοποιήστε τη μέθοδο `firstIsDefault()` για να κάνετε το πρώτο στοιχείο προεπιλεγμένο:

```php
// η προεπιλογή είναι 'hello'
Expect::anyOf(Expect::string('hello'), true, null)->firstIsDefault();
```


Δομές .[#toc-structures]
------------------------

Οι δομές είναι αντικείμενα με καθορισμένα κλειδιά. Κάθε ένα από αυτά τα ζεύγη κλειδί => τιμή αναφέρεται ως "ιδιότητα":

Οι δομές δέχονται πίνακες και αντικείμενα και επιστρέφουν αντικείμενα `stdClass`.

Από προεπιλογή, όλες οι ιδιότητες είναι προαιρετικές και έχουν προεπιλεγμένη τιμή `null`. Μπορείτε να ορίσετε υποχρεωτικές ιδιότητες χρησιμοποιώντας το `required()`:

```php
$schema = Expect::structure([
	'required' => Expect::string()->required(),
	'optional' => Expect::string(), // η προεπιλεγμένη τιμή είναι null
]);

$processor->process($schema, ['optional' => '']);
// ERROR: option 'required' is missing

$processor->process($schema, ['required' => 'foo']);
// OK, returns {'required' => 'foo', 'optional' => null}
```

Εάν δεν θέλετε να εξάγετε ιδιότητες με μόνο μια προεπιλεγμένη τιμή, χρησιμοποιήστε το `skipDefaults()`:

```php
$schema = Expect::structure([
	'required' => Expect::string()->required(),
	'optional' => Expect::string(),
])->skipDefaults();

$processor->process($schema, ['required' => 'foo']);
// OK, επιστρέφει {'required' => 'foo'}
```

Παρόλο που το `null` είναι η προεπιλεγμένη τιμή της ιδιότητας `optional`, δεν επιτρέπεται στα δεδομένα εισόδου (η τιμή πρέπει να είναι συμβολοσειρά). Οι ιδιότητες που δέχονται το `null` ορίζονται χρησιμοποιώντας το `nullable()`:

```php
$schema = Expect::structure([
	'optional' => Expect::string(),
	'nullable' => Expect::string()->nullable(),
]);

$processor->process($schema, ['optional' => null]);
// ERROR: 'optional' αναμένει να είναι string, null given.

$processor->process($schema, ['nullable' => null]);
// OK, επιστρέφει {'optional' => null, 'nullable' => null}
```

Ο πίνακας όλων των ιδιοτήτων της δομής επιστρέφεται από τη μέθοδο `getShape()`.

Από προεπιλογή, δεν μπορούν να υπάρχουν επιπλέον στοιχεία στα δεδομένα εισόδου:

```php
$schema = Expect::structure([
	'key' => Expect::string(),
]);

$processor->process($schema, ['additional' => 1]);
// ΣΦΑΛΜΑ: Μη αναμενόμενο στοιχείο 'additional'
```

Το οποίο μπορούμε να αλλάξουμε με το `otherItems()`. Ως παράμετρος, θα καθορίσουμε το σχήμα για κάθε επιπλέον στοιχείο:

```php
$schema = Expect::structure([
	'key' => Expect::string(),
])->otherItems(Expect::int());

$processor->process($schema, ['additional' => 1]); // OK
$processor->process($schema, ['additional' => true]); // ΣΦΑΛΜΑ
```

Μπορείτε να δημιουργήσετε μια νέα δομή παράγοντας από μια άλλη χρησιμοποιώντας το `extend()`:

```php
$dog = Expect::structure([
	'name' => Expect::string(),
	'age' => Expect::int(),
]);

$dogWithBreed = $dog->extend([
	'breed' => Expect::string(),
]);
```


Συστοιχία .[#toc-array]
-----------------------

Ένας πίνακας με καθορισμένα κλειδιά. Ισχύουν οι ίδιοι κανόνες όπως και για [τις δομές |#structure].

```php
$schema = Expect::array([
	'required' => Expect::string()->required(),
	'optional' => Expect::string(), // default value is null
]);
```

Μπορείτε επίσης να ορίσετε έναν δεικτοδοτούμενο πίνακα, γνωστό ως πλειάδα:

```php
$schema = Expect::array([
	Expect::int(),
	Expect::string(),
	Expect::bool(),
]);

$processor->process($schema, [1, 'hello', true]); // OK
```


Αποσβέσεις .[#toc-deprecations]
-------------------------------

Μπορείτε να καταργήσετε μια ιδιότητα χρησιμοποιώντας την εντολή `deprecated([string $message])` μέθοδο. Οι ειδοποιήσεις κατάργησης επιστρέφονται από το `$processor->getWarnings()`:

```php
$schema = Expect::structure([
	'old' => Expect::int()->deprecated('The item %path% is deprecated'),
]);

$processor->process($schema, ['old' => 1]); // OK
$processor->getWarnings(); // ["The item 'old' is deprecated"]
```


Εύρος: min() max() .[#toc-ranges-min-max]
-----------------------------------------

Χρησιμοποιήστε τα `min()` και `max()` για να περιορίσετε τον αριθμό των στοιχείων των πινάκων:

```php
// πίνακας, τουλάχιστον 10 στοιχεία, μέγιστο 20 στοιχεία
Expect::array()->min(10)->max(20);
```

Για συμβολοσειρές, περιορίστε το μήκος τους:

```php
// συμβολοσειρά, τουλάχιστον 10 χαρακτήρες, το πολύ 20 χαρακτήρες
Expect::string()->min(10)->max(20);
```

Για αριθμούς, περιορίστε την τιμή τους:

```php
// ακέραιος αριθμός, μεταξύ 10 και 20 συμπεριλαμβανομένου
Expect::int()->min(10)->max(20);
```

Φυσικά, είναι δυνατόν να αναφέρετε μόνο το `min()` ή μόνο το `max()`:

```php
// συμβολοσειρά, μέγιστο 20 χαρακτήρες
Expect::string()->max(20);
```


Κανονικές εκφράσεις: pattern() .[#toc-regular-expressions-pattern]
------------------------------------------------------------------

Χρησιμοποιώντας το `pattern()`, μπορείτε να καθορίσετε μια κανονική έκφραση με την οποία πρέπει να ταιριάζει **όλη** η συμβολοσειρά εισόδου (δηλαδή σαν να ήταν τυλιγμένη σε χαρακτήρες `^` a `$`):

```php
// μόλις 9 ψηφία
Expect::string()->pattern('\d{9}');
```


assert() .[#toc-custom-assertions-assert]
-----------------------------------------

Μπορείτε να προσθέσετε οποιουσδήποτε άλλους περιορισμούς χρησιμοποιώντας το `assert(callable $fn)`.

```php
$countIsEven = fn($v) => count($v) % 2 === 0;

$schema = Expect::arrayOf('string')
	->assert($countIsEven); // η καταμέτρηση πρέπει να είναι ζυγός

$processor->process($schema, ['a', 'b']); // OK
$processor->process($schema, ['a', 'b', 'c']); // ΣΦΑΛΜΑ: Το 3 δεν είναι άρτιο
```

Ή

```php
Expect::string()->assert('is_file'); // το αρχείο πρέπει να υπάρχει
```

Μπορείτε να προσθέσετε τη δική σας περιγραφή για κάθε ισχυρισμό. Θα είναι μέρος του μηνύματος σφάλματος.

```php
$schema = Expect::arrayOf('string')
	->assert($countIsEven, 'Even items in array');

$processor->process($schema, ['a', 'b', 'c']);
// Αποτυχημένος ισχυρισμός "Even items in array" για στοιχείο με τιμή array.
```

Η μέθοδος μπορεί να κληθεί επανειλημμένα για την προσθήκη πολλαπλών περιορισμών. Μπορεί να αναμειχθεί με κλήσεις στις `transform()` και `castTo()`.


Μετασχηματισμός: transform() .[#toc-transformation-transform]
-------------------------------------------------------------

Τα επιτυχώς επικυρωμένα δεδομένα μπορούν να τροποποιηθούν χρησιμοποιώντας μια προσαρμοσμένη συνάρτηση:

```php
// conversion to uppercase:
Expect::string()->transform(fn(string $s) => strtoupper($s));
```

Η μέθοδος μπορεί να κληθεί επανειλημμένα για την προσθήκη πολλαπλών μετασχηματισμών. Μπορεί να αναμειχθεί με κλήσεις στις `assert()` και `castTo()`. Οι λειτουργίες θα εκτελούνται με τη σειρά με την οποία δηλώνονται:

```php
Expect::type('string|int')
	->castTo('string')
	->assert('ctype_lower', 'All characters must be lowercased')
	->transform(fn(string $s) => strtoupper($s)); // conversion to uppercase
```

Η μέθοδος `transform()` μπορεί να μετασχηματίσει και να επικυρώσει την τιμή ταυτόχρονα. Αυτό είναι συχνά απλούστερο και λιγότερο περιττό από την αλυσιδωτή εκτέλεση των `transform()` και `assert()`. Για το σκοπό αυτό, η συνάρτηση λαμβάνει ένα αντικείμενο [Context |api:Nette\Schema\Context] με μια μέθοδο `addError()`, η οποία μπορεί να χρησιμοποιηθεί για την προσθήκη πληροφοριών σχετικά με τα θέματα επικύρωσης:

```php
Expect::string()
	->transform(function (string $s, Nette\Schema\Context $context) {
		if (!ctype_lower($s)) {
			$context->addError('All characters must be lowercased', 'my.case.error');
			return null;
		}

		return strtoupper($s);
	});
```


Casting: castTo() .[#toc-casting-castto]
----------------------------------------

Τα επιτυχώς επικυρωμένα δεδομένα μπορούν να μεταφερθούν:

```php
Expect::scalar()->castTo('string');
```

Εκτός από τους εγγενείς τύπους της PHP, μπορείτε επίσης να κάνετε cast σε κλάσεις. Διακρίνεται αν πρόκειται για μια απλή κλάση χωρίς κατασκευαστή ή για μια κλάση με κατασκευαστή. Αν η κλάση δεν έχει κατασκευαστή, δημιουργείται μια παρουσία της και όλα τα στοιχεία της δομής γράφονται στις ιδιότητές της:

```php
class Info
{
	public bool $processRefund;
	public int $refundAmount;
}

Expect::structure([
	'processRefund' => Expect::bool(),
	'refundAmount' => Expect::int(),
])->castTo(Info::class);

// creates '$obj = new Info' and writes to $obj->processRefund and $obj->refundAmount
```

Εάν η κλάση διαθέτει κατασκευαστή, τα στοιχεία της δομής μεταβιβάζονται ως ονομαστικές παράμετροι στον κατασκευαστή:

```php
class Info
{
	public function __construct(
		public bool $processRefund,
		public int $refundAmount,
	) {
	}
}

// creates $obj = new Info(processRefund: ..., refundAmount: ...)
```

Η χύτευση σε συνδυασμό με μια κλιμακωτή παράμετρο δημιουργεί ένα αντικείμενο και μεταβιβάζει την τιμή ως μοναδική παράμετρο στον κατασκευαστή:

```php
Expect::string()->castTo(DateTime::class);
// creates new DateTime(...)
```


Κανονικοποίηση: before() .[#toc-normalization-before]
-----------------------------------------------------

Πριν από την ίδια την επικύρωση, τα δεδομένα μπορούν να κανονικοποιηθούν χρησιμοποιώντας τη μέθοδο `before()`. Ως παράδειγμα, ας έχουμε ένα στοιχείο που πρέπει να είναι ένας πίνακας συμβολοσειρών (π.χ. `['a', 'b', 'c']`), αλλά δέχεται είσοδο με τη μορφή συμβολοσειράς `a b c`:

```php
$explode = fn($v) => explode(' ', $v);

$schema = Expect::arrayOf('string')
	->before($explode);

$normalized = $processor->process($schema, 'a b c');
// OK, επιστρέφει ['a', 'b', 'c']
```


Αντιστοίχιση σε αντικείμενα: from() .[#toc-mapping-to-objects-from]
-------------------------------------------------------------------

Μπορείτε να δημιουργήσετε σχήμα δομής από την κλάση. Παράδειγμα:

```php
class Config
{
	public string $name;
	public string|null $password;
	public bool $admin = false;
}

$schema = Expect::from(new Config);

$data = [
	'name' => 'jeff',
];

$normalized = $processor->process($schema, $data);
// $normalized instanceof Config
// $normalized = {'name' => 'jeff', 'password' => null, 'admin' => false}
```

Υποστηρίζονται επίσης ανώνυμες κλάσεις:

```php
$schema = Expect::from(new class {
	public string $name;
	public ?string $password;
	public bool $admin = false;
});
```

Μπορείτε να προσθέσετε ένα προσαρμοσμένο σχήμα για τα στοιχεία με τη δεύτερη παράμετρο:

```php
$schema = Expect::from(new Config, [
	'name' => Expect::string()->pattern('\w:.*'),
]);
```

{{leftbar: nette:@menu-topics}}