slashlab/numerik

Modern PHP 8.3+ library for validating and parsing Polish identification numbers (PESEL, NIP, REGON, KRS, NRB, VAT-EU, IBAN, ID Card, Passport).

v1.2.0 2026-07-16 16:27 UTC

Requires

• php: ^8.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95.15
• infection/infection: ^0.29
• phpstan/phpstan: ^2.2.5
• phpstan/phpstan-strict-rules: ^2.0.11
• phpunit/phpunit: ^12.5.31

MIT

• Sqrcz

• validator
• validation
• pesel
• regon
• nip
• polish
• passport
• IBAN
• id-card
• krs
• poland
• nrb
• numerik
• vat-eu

Published on Packagist.org on 2026-07-16 16:28 UTC

README

Modern PHP 8.3+ library for validating and parsing Polish identification numbers — PESEL, NIP, REGON, KRS, NRB, VAT-EU, IBAN, ID Card, and Passport. Rich value objects, detailed error reasons, zero production dependencies.

Installation

composer require slashlab/numerik

Quick Start

use SlashLab\Numerik\Numerik;

// Simple boolean check
Numerik::pesel()->isValid('92060512186');  // true
Numerik::nip()->isValid('5260250274');     // true

// Rich validation result with failure reasons
$result = Numerik::pesel()->validate('92060512185');  // wrong checksum digit
$result->isFailed();                       // true
$result->getFirstFailure()->reason;        // ValidationFailureReason::InvalidChecksum

// Parse to value object
$pesel = Numerik::pesel()->parse('92060512186');
$pesel->getBirthDate()->format('Y-m-d');  // '1992-06-05'
$pesel->getGender();                      // Gender::Female

// Try-parse — returns null on failure instead of throwing
$nip = Numerik::nip()->tryParse('5260250274');
$nip?->getFormatted();                     // '526-025-02-74'

Strict Mode

All identifiers accept an optional strict parameter (default true), and it never affects how input is normalized — normalization (stripping spaces, and dashes where the format allows them) is the same in both modes. What strict gates is extra semantic plausibility checks: rejecting all-same-digit numbers (PESEL, NIP, KRS, VAT-EU) and future birth dates (PESEL). ID Card, Passport, REGON, NRB, and IBAN have no additional strict-mode checks.

Numerik::nip(strict: false)->isValid('1111111111');  // true
Numerik::nip(strict: true)->isValid('1111111111');   // false — all-same-digit

Documentation

Full documentation at numerik.slashlab.pl

JavaScript / TypeScript Port

A TypeScript port is available at @slashlab/numerik-js. It mirrors this library's API — same identifiers, same value objects, same strict mode — with Zod integration included.

npm install @slashlab/numerik-js

Laravel Integration

A dedicated Laravel package is available at slashlab/numerik-laravel (PHP 8.3+, Laravel 12/13). It provides class-based and string-based validation rules with per-failure-reason error messages, English and Polish translations, and extended PeselRule constraints (gender, bornBefore, bornAfter).

composer require slashlab/numerik-laravel

See the numerik-laravel README for full usage.

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT — see LICENSE.

If this saved you time → ☕ Buy me a coffee