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.1.0 2026-05-07 22:16 UTC

Requires

• php: ^8.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• infection/infection: ^0.29
• phpstan/phpstan: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.0

MIT

• Sqrcz

• validator
• validation
• pesel
• regon
• nip
• polish
• krs
• poland
• numerik

Published on Packagist.org on 2026-05-07 22:03 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). In non-strict mode, formatting variations such as spaces and dashes are accepted:

Numerik::nip(strict: false)->isValid('526 025 02 74');  // true
Numerik::nip(strict: true)->isValid('526 025 02 74');   // false

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