Wyniki walidacji

Metody isValid() i validate() są dostępne na każdej klasie identyfikatora i nigdy nie rzucają wyjątku.

ValidationResult

validate() zwraca klasę readonly SlashLab\Numerik\Result\ValidationResult.

Właściwości

Właściwość	Typ	Opis
$isValid	bool	true jeśli walidacja zakończyła się sukcesem.
$failures	list<ValidationFailure>	Pusta tablica przy poprawnym numerze; jeden lub więcej błędów przy nieprawidłowym.

Metody

Metoda	Typ zwracany	Opis
isFailed()	bool	Negacja $isValid.
getFailures()	list<ValidationFailure>	Zwraca tablicę błędów.
getFirstFailure()	ValidationFailure|null	Pierwszy błąd lub null przy poprawnym wejściu.
hasFailureReason(ValidationFailureReason $reason)	bool	true jeśli którykolwiek błąd pasuje do podanego powodu.

Przykłady

use SlashLab\Numerik\Numerik;
use SlashLab\Numerik\Enums\ValidationFailureReason;

// Wynik pozytywny
$result = Numerik::pesel()->validate('92060512186');

$result->isValid;           // true
$result->isFailed();        // false
$result->failures;          // []
$result->getFirstFailure(); // null

// Wynik negatywny
$result = Numerik::nip()->validate('0000000000');

$result->isValid;           // false
$result->isFailed();        // true

// Sprawdź pierwszy (i zazwyczaj jedyny) błąd
$failure = $result->getFirstFailure();
$failure->reason;           // ValidationFailureReason::InvalidFormat
$failure->message;          // 'NIP tax office code cannot be 000.'

// Sprawdź konkretny powód
$result->hasFailureReason(ValidationFailureReason::InvalidChecksum); // false
$result->hasFailureReason(ValidationFailureReason::InvalidFormat);   // true

ValidationFailure

Każdy element w $failures to klasa readonly SlashLab\Numerik\Result\ValidationFailure.

Właściwości

Właściwość	Typ	Opis
$reason	ValidationFailureReason	Przypadek enum identyfikujący kategorię błędu.
$message	string	Opis błędu przeznaczony do logowania i debugowania.

Enum ValidationFailureReason

SlashLab\Numerik\Enums\ValidationFailureReason to backed string enum.

Błędy formatu

Przypadek	Wartość	Opis
InvalidLength	invalid_length	Numer ma nieprawidłową liczbę cyfr.
InvalidCharacters	invalid_characters	Po usunięciu dozwolonych separatorów pozostały niedozwolone znaki.
InvalidFormat	invalid_format	Długość i znaki są poprawne, ale numer narusza regułę strukturalną (np. kod urzędu skarbowego NIP 000).

Błędy sumy kontrolnej

Przypadek	Wartość	Opis
InvalidChecksum	invalid_checksum	Obliczona suma kontrolna nie zgadza się z cyfrą kontrolną.

Błędy zakodowanej daty

Przypadek	Wartość	Opis
InvalidDate	invalid_date	Data zakodowana w identyfikatorze nie istnieje w kalendarzu.
FutureDate	future_date	Zakodowana data urodzenia jest w przyszłości.
InvalidMonth	invalid_month	Kodowanie miesiąca nie odpowiada żadnemu ze znanych zakresów stulecia.

Błędy semantyczne

Przypadek	Wartość	Opis
AllZeros	all_zeros	Wszystkie cyfry są zerami — strukturalnie możliwe, ale semantycznie nieprawidłowe.
AllSameDigit	all_same_digit	Wszystkie cyfry są takie same i niezerowe.

Pomocnicze konstruktory

ValidationResult udostępnia trzy statyczne konstruktory przydatne przy pisaniu testów:

// Sukces
ValidationResult::pass();

// Niepowodzenie z listą błędów
ValidationResult::fail([
    new ValidationFailure(ValidationFailureReason::InvalidChecksum, 'Checksum mismatch.'),
]);

// Niepowodzenie z jednym powodem — skrócona forma
ValidationResult::failWithReason(
    ValidationFailureReason::InvalidLength,
    'Expected 11 digits, got 10.',
);