Integracja z Laravel

slashlab/numerik-laravel dodaje walidatory Numerika jako reguły walidacji Laravel. Obsługuje zarówno składnię klasową jak i łańcuchową i jest automatycznie wykrywany — nie wymaga ręcznej rejestracji.

Wymagania

• PHP 8.3 lub nowszy
• Laravel 11, 12 lub 13

Instalacja

1. Dodaj pakiet

   composer require slashlab/numerik-laravel

2. Brak konfiguracji

   Biblioteka jest automatycznie wykrywana — nie ma pliku konfiguracyjnego do opublikowania ani kroku inicjalizacji.

Użycie

Reguły klasowe

use SlashLab\NumerikLaravel\Rules\PeselRule;
use SlashLab\NumerikLaravel\Rules\NipRule;
use SlashLab\NumerikLaravel\Rules\RegonRule;
use SlashLab\NumerikLaravel\Rules\KrsRule;

public function rules(): array
{
    return [
        'pesel' => ['required', new PeselRule()],
        'nip'   => ['required', new NipRule()],
        'regon' => ['required', new RegonRule()],
        'krs'   => ['required', new KrsRule()],
    ];
}

Reguły łańcuchowe

Używaj zwykłych łańcuchów gdy nie potrzebujesz opcji konstruktora. Reguły są rejestrowane pod nazwą identyfikatora pisaną małymi literami.

public function rules(): array
{
    return [
        'pesel' => ['required', 'pesel'],
        'nip'   => ['required', 'nip'],
        'regon' => ['required', 'regon'],
        'krs'   => ['required', 'krs'],
    ];
}

Uwaga

Reguły łańcuchowe zawsze zwracają ogólny komunikat walidacji, niezależnie od przyczyny błędu. Używaj reguł klasowych gdy konkretne komunikaty mają znaczenie — np. gdy chcesz rozróżnić złą sumę kontrolną od nieprawidłowej długości.

Komunikaty walidacji

Reguły klasowe zwracają osobny komunikat dla każdego powodu błędu. NIP z nieprawidłową sumą kontrolną dostanie inny komunikat niż NIP z nieprawidłową długością.

Komunikaty rozpoznają etykietę pola z validation.attributes, jeśli jest zdefiniowana — zachowują się jak wbudowane reguły Laravel. Jeśli etykieta nie jest zarejestrowana, nazwa pola jest automatycznie formatowana: podkreślenia zamieniają się na spacje, pierwsza litera staje się wielka.

lang/en/validation.php

'attributes' => [
    'nip_number' => 'NIP',
],

Pakiet zawiera tłumaczenia na angielski (en) i polski (pl). Aby opublikować i dostosować komunikaty:

php artisan vendor:publish --tag=numerik-lang

Pliki tłumaczeń trafią do lang/vendor/numerik/ — edytuj je, żeby nadpisać dowolny komunikat.

Tryb ścisły

Wszystkie reguły przyjmują opcjonalny parametr strict (domyślnie true). W trybie ścisłym poza walidacją strukturalną i sumą kontrolną stosowane są dodatkowe sprawdzenia semantyczne.

Dla numeru PESEL tryb ścisły odrzuca numery z datą urodzenia w przyszłości lub wszystkimi identycznymi cyframi:

// Tryb ścisły włączony (domyślnie) — odrzuca daty przyszłe i podejrzane wzorce
new PeselRule()

// Tryb ścisły wyłączony — stosowane są tylko sprawdzenia strukturalne i sumy kontrolnej
new PeselRule(strict: false)

Ten sam parametr jest akceptowany przez NipRule, RegonRule i KrsRule.

Wskazówka

Wyłącz tryb ścisły gdy potrzebujesz akceptować dane testowe lub syntetyczne — fikcyjne numery jak 22222222222 są typowe w środowiskach typu staging.

Ograniczenia PESEL

PeselRule obsługuje dodatkowe ograniczenia weryfikowane po przejściu podstawowej walidacji.

Płeć

Odrzucaj numery, które nie odpowiadają oczekiwanej płci:

use SlashLab\Numerik\Enums\Gender;

new PeselRule(gender: Gender::Male)
new PeselRule(gender: Gender::Female)

Zakres daty urodzenia

Odrzucaj numery, których zakodowana data urodzenia wykracza poza podany zakres:

new PeselRule(bornBefore: new DateTimeImmutable('2000-01-01'))
new PeselRule(bornAfter:  new DateTimeImmutable('1980-12-31'))

Ograniczenia można łączyć:

new PeselRule(
    gender:     Gender::Female,
    bornAfter:  new DateTimeImmutable('1990-01-01'),
    bornBefore: new DateTimeImmutable('2005-01-01'),
)

Linki

• GitHub: github.com/Sqrcz/numerik-laravel
• Packagist: packagist.org/packages/slashlab/numerik-laravel