README

A PHP library for validating and parsing Serbian unique master citizen numbers (JMBG - Jedinstveni Matični Broj Građana).

Features

✅ Validate JMBG numbers with comprehensive checks
✅ Extract birth date, region, and gender information
✅ Support for all Serbian regions
✅ Calculate age from JMBG
✅ Type-safe with PHP 8.1+ features
✅ Fully tested with PHPUnit
✅ PSR-12 compliant code

Installation

Install via Composer:

composer require jmbg-labs/jmbg

Usage

Basic Validation

use JmbgLabs\Jmbg\Jmbg;

// Quick validation
if (Jmbg::valid('0101000710009')) {
    echo "Valid JMBG";
}

// Parse and validate
try {
    $jmbg = Jmbg::parse('0101000710009');
    echo "Valid JMBG: " . $jmbg->format();
} catch (JmbgException $e) {
    echo "Invalid JMBG: " . $e->getMessage();
}

Extract Information

use JmbgLabs\Jmbg\Jmbg;

$jmbg = new Jmbg('0101000710009');

// Get birth date
$date = $jmbg->getDate(); // DateTime object
echo $date->format('Y-m-d'); // 2000-01-01

// Get age
echo $jmbg->getAge(); // e.g., 26

// Check gender
if ($jmbg->isMale()) {
    echo "Male";
}

if ($jmbg->isFemale()) {
    echo "Female";
}

// Access individual parts
echo $jmbg->day;           // 1
echo $jmbg->month;         // 1
echo $jmbg->year;          // 2000
echo $jmbg->region;        // 71
echo $jmbg->region_text;   // "Belgrade"
echo $jmbg->country;       // "Serbia"
echo $jmbg->unique;        // 0
echo $jmbg->checksum;      // 9

Using Magic Methods

$jmbg = new Jmbg('1505995800002');

// String conversion
echo (string)$jmbg; // "1505995800002"
echo $jmbg->format(); // "1505995800002"

// Property access
echo $jmbg->original;        // "1505995800002"
echo $jmbg->day_original;    // "15"
echo $jmbg->month_original;  // "05"
echo $jmbg->year_original;   // "995"
echo $jmbg->region_original; // "80"
echo $jmbg->unique_original; // "000"

// Check property existence
if (isset($jmbg->region_text)) {
    echo $jmbg->region_text; // "Novi Sad"
}

JMBG Format

JMBG consists of 13 digits: DDMMYYYRRBBBC

DD - Day of birth (01-31)
MM - Month of birth (01-12)
YYY - Year of birth (last 3 digits)
RR - Region code
BBB - Unique number (000-499 for males, 500-999 for females)
C - Checksum digit

Supported Regions

The library supports all Serbian and ex-Yugoslav regions including (beware: ex-Yugoslav regions codes may have changed since the breakup):

Serbia (71-79): Belgrade, Kragujevac, Niš, etc.
Serbia/Vojvodina (80-89): Novi Sad, Subotica, Pančevo, etc.
Serbia/Kosovo (91-96): Priština, Peć, Prizren, etc.
Bosnia and Herzegovina (10-19)
Montenegro (21-29)
Croatia (30-39)
Macedonia (41-49)
Slovenia (50)

Validation Rules

The library performs comprehensive validation:

Length check - Must be exactly 13 digits
Format check - Must contain only numeric characters
Date validation - Birth date must be valid (including leap year support)
Region validation - Region code must exist in the registry
Checksum validation - Modulo 11 algorithm verification

Development

Running Tests

# Run all tests
composer test

# Run tests with coverage
composer test-coverage

Code Style

# Check code style
composer cs

# Fix code style issues
composer cs-fix

Requirements

PHP ^8.1
No external dependencies (for production use)

Contributing

Contributions are welcome! Please ensure:

All tests pass (composer test)
Code follows PSR-12 standards (composer cs)
Add tests for new features
Update documentation as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Developed by JMBG Labs

Support

🐛 Report Issues
📖 Source Code

Examples

Validate Multiple JMBGs

$jmbgs = ['0710003730015', '1705978730032', 'invalid'];

foreach ($jmbgs as $jmbgString) {
    if (Jmbg::valid($jmbgString)) {
        $jmbg = Jmbg::parse($jmbgString);
        echo sprintf(
            "%s - Born: %s, Region: %s, Gender: %s\n",
            $jmbg->format(),
            $jmbg->getDate()->format('Y-m-d'),
            $jmbg->region_text,
            $jmbg->isMale() ? 'Male' : 'Female'
        );
    } else {
        echo "$jmbgString - Invalid\n";
    }
}

Age Calculation

$jmbg = new Jmbg('0710003730015');
$age = $jmbg->getAge();

if ($age >= 18) {
    echo "Adult";
} else {
    echo "Minor";
}

Error Handling

use JmbgLabs\Jmbg\Jmbg;
use JmbgLabs\Jmbg\JmbgException;

try {
    $jmbg = new Jmbg('1234567890123');
} catch (JmbgException $e) {
    // Handle specific validation errors
    echo "Validation failed: " . $e->getMessage();
    // Possible messages:
    // - "Input string must have 13 digits."
    // - "JMBG string must have 13 digits."
    // - "Date '...' is not valid."
    // - "Region '...' is not valid for Serbian JMBG."
    // - "Checksum is not valid."
}

jmbg-labs / jmbg

Maintainers

Package info

Statistics

Security