Obsługa błędów

• isValid() i validate() nigdy nie rzucają wyjątków - zawsze zwracają wartość.
• parse() dla nieprawidłowych danych rzuca wyjątek ValidationException z konkretnym powodem błędu.
• tryParse() dla nieprawidłowych danych zwraca null.

Wszystkie cztery metody są dostępne w każdej z klas identyfikatora.

Hierarchia wyjątków

Wszystkie wyjątki dziedziczą po SlashLab\Numerik\Exceptions\ValidationException, która dziedziczy po \RuntimeException.

\RuntimeException
└── ValidationException
    ├── InvalidFormatException    — zła długość lub nieprawidłowe znaki
    ├── InvalidChecksumException  — niezgodność cyfry kontrolnej
    └── InvalidDateException      — niemożliwa data zakodowana wewnątrz identyfikatora

Wszystkie klasy wyjątków znajdują się w przestrzeni nazw SlashLab\Numerik\Exceptions.

Kiedy pojawia się każdy wyjątek

Wyjątek	Warunek
InvalidFormatException	Nieprawidłowa długość, niedozwolone znaki lub naruszenie reguły strukturalnej (np. kod urzędu skarbowego NIP 000).
InvalidChecksumException	Cyfra kontrolna nie zgadza się z obliczoną wartością.
InvalidDateException	Data zakodowana w PESEL jest niemożliwa — nieprawidłowy miesiąc, nieistniejąca data kalendarzowa lub data urodzenia w przyszłości.

Przechwytywanie wyjątków

use SlashLab\Numerik\Numerik;
use SlashLab\Numerik\Exceptions\ValidationException;
use SlashLab\Numerik\Exceptions\InvalidFormatException;
use SlashLab\Numerik\Exceptions\InvalidChecksumException;
use SlashLab\Numerik\Exceptions\InvalidDateException;

// Przechwytywanie dowolnego błędu walidacji
try {
    $pesel = Numerik::pesel()->parse($input);
} catch (ValidationException $e) {
    // obsłuż dowolny błąd parsowania
    echo $e->getMessage();
}

// Przechwytywanie konkretnych błędów
try {
    $pesel = Numerik::pesel()->parse($input);
} catch (InvalidFormatException $e) {
    // zła długość lub znaki
} catch (InvalidChecksumException $e) {
    // niezgodność sumy kontrolnej
} catch (InvalidDateException $e) {
    // niemożliwa data urodzenia zakodowana wewnątrz
}

Wybór między parse() a validate()

Wskazówka

Jeśli potrzebujesz tylko sprawdzić, czy numer jest prawidłowy — użyj validate() lub isValid(). Obie metody nigdy nie rzucają wyjątków i są bezpieczne do wywołania na dowolnych niezaufanych danych wejściowych bez owijania w try/catch.

Użyj parse(), gdy potrzebujesz wyodrębnionych danych z numeru i wolisz obsługiwać błędy przez wyjątki — np. wewnątrz serwisu, który już ma blok catch.

Użyj tryParse(), gdy również potrzebujesz wyodrębnionych danych z numeru, ale zamiast wyjątku wolisz dostać null — przydatne w pętlach lub potokach importu danych.

// Rzuca przy nieprawidłowym numerze
$pesel = Numerik::pesel()->parse($input);

// Zwraca null przy nieprawidłowym numerze
$pesel = Numerik::pesel()->tryParse($input);
if ($pesel === null) {
    // obsłuż nieprawidłowy numer
}

Tryb ścisły

Wszystkie klasy identyfikatorów przyjmują parametr konstruktora strict (domyślnie true). W trybie ścisłym wejścia, które przechodzą wszystkie sprawdzenia algorytmiczne, ale wyglądają podejrzanie — np. ciąg złożony z jednej powtarzającej się cyfry — są odrzucane z ValidationFailureReason::AllSameDigit.

// Tryb ścisły włączony (domyślnie) — odrzuca podejrzane-ale-poprawne wejścia
Numerik::pesel()->validate('11111111111');           // błąd: AllSameDigit

// Tryb ścisły wyłączony — akceptuje wszystko strukturalnie i algorytmicznie poprawne
Numerik::pesel(strict: false)->validate('11111111111'); // przechodzi

Wyłącz tryb ścisły gdy przetwarzasz dane historyczne zawierające wartości zastępcze albo gdy chcesz odróżnić „strukturalnie nieprawidłowe” od „algorytmicznie poprawne, ale podejrzane” w potoku jakości danych.

Ochrona przed długością wejścia

Wszystkie metody natychmiast odrzucają wejścia dłuższe niż 32 znaki, zanim jakiekolwiek przetwarzanie się rozpocznie — zabezpieczenie przed potencjalnymi atakami DoS przez bardzo duże ciągi.