Cześć,
Chciałbym pokazać projekt, nad którym ostatnio pracowałem: Numerik — zestaw bibliotek do walidacji i parsowania polskich numerów identyfikacyjnych: PESEL, NIP, REGON, KRS, NRB, VAT-EU, IBAN, dowód osobisty i paszport.
Dlaczego kolejna biblioteka do tego?
Istniejące rozwiązania (np. kiczort/polish-validator w PHP, validate-polish w JS) działają, ale zwykle:
- zwracają jedynie
true/false, nie mówiąc nic o tym, dlaczego walidacja zawiodła, - opierają się na wyrażeniach regularnych,
- nie dają dostępu do sparsowanych danych (daty urodzenia, płci, wieku) w gotowej postaci — to trzeba dopisać samodzielnie.
Co Numerik robi inaczej
- Zero zależności — PHP 8.3+,
declare(strict_types=1)wszędzie. - Bogate value objecty —
parse()zwraca np. dla PESEL obiekt zgetBirthDate(),getGender(),getAge(),isAdult(). - Typowane przyczyny błędów — enum
ValidationFailureReason(InvalidChecksum,FutureDate,InvalidMonthitd.) zamiast prostego boolean'a. - Bez wyrażeń regularnych — cała logika to operacje na tablicach cyfr, więc zero ryzyka ReDoS.
- PHPStan poziom 10, testy mutacyjne (Infection), pełne CI.
Przykład
use SlashLab\Numerik\Numerik;
Numerik::pesel()->isValid('92060512186'); // true
$result = Numerik::pesel()->validate('92060512185'); // zły checksum
$result->isFailed(); // true
$result->getFirstFailure()->reason; // ValidationFailureReason::InvalidChecksum
$pesel = Numerik::pesel()->parse('92060512186');
$pesel->getBirthDate()->format('Y-m-d'); // '1992-06-05'
$pesel->getGender(); // Gender::Female
$pesel->getAge(); // liczone od dziś
Instalacja
composer require slashlab/numerik
Dodatkowe pakiety
- slashlab/numerik-laravel — gotowe reguły walidacji dla Laravela (
Validator::make(), Form Requests), z tłumaczeniami PL/EN. - @slashlab/numerik-js — port na TypeScript, ten sam interfejs, z integracją Zod.
Linki
- GitHub: https://github.com/sqrcz/numerik
- Dokumentacja: https://numerik.slashlab.pl / https://numerik-js.slashlab.pl/
- Packagist: https://packagist.org/packages/slashlab/numerik
Projekt jest świeży i cały czas rozwijany — chętnie usłyszę uwagi, zwłaszcza jeśli ktoś zna edge case'y w tych numerach, których jeszcze nie obsłużyłem.
