README

A Laravel package for validating, parsing, and generating Bulgarian EGN numbers (ЕГН).

Features

• Validate Bulgarian EGN numbers
• Parse EGN into birth date and gender
• Generate valid EGN numbers with optional constraints:
  • gender (male|female|m|f)
  • exact date (date) or partial date (year, month, day)
  • region prefix (0..99)
  • batch generation (generate($count, ...))
• Resolve rich EGN metadata via details():
  • localized output (bg / en)
  • birth date formatting and weekday
  • age
  • region name and serial range
  • birth order within region parity
  • zodiac sign
• Native Laravel validation rule: egn

Requirements

• PHP ^8.1
• Laravel components:
  • illuminate/support ^10.0|^11.0|^12.0
  • illuminate/validation ^10.0|^11.0|^12.0

Installation

composer require metalinvestremko/laravel-egn

Configuration (Optional)

Publish the config file:

php artisan vendor:publish --tag=egn-config

Config file: config/egn.php

return [
    'start_year' => 1800,
    'end_year' => 2099,
];

These values define the default random generation range when year is not explicitly provided.

Usage

Validate EGN

use MetalinvestRemko\LaravelEgn\Facades\Egn;

$isValid = Egn::validate('6101057509'); // true

Laravel Validation Rule

$request->validate([
    'egn' => ['required', 'egn'],
]);

Parse EGN

$parsed = Egn::parse('6101057509');

// [
//   'year' => 1961,
//   'month' => 1,
//   'day' => 5,
//   'gender' => 0, // 0 = female, 1 = male
// ]

Get Detailed Metadata

$detailsArray = Egn::details('8702260780'); // default format: array
$detailsObject = Egn::details('8702260780', 'object');
$detailsCollection = Egn::details('8702260780', 'collection');
$detailsEn = Egn::details('8702260780', 'array', 'en');

details() returns null for invalid EGN.

Locale behavior:

• If locale is provided, only bg and en are accepted
• Unsupported locale values fallback to bg
• If locale is omitted, package attempts app()->getLocale() and still restricts to bg|en

Example (array, en locale):

[
    'egn' => '8702260780',
    'valid' => true,
    'locale' => 'en',
    'gender' => 'female',
    'gender_code' => 'female',
    'birth_date' => [
        'iso' => '1987-02-26',
        'year' => 1987,
        'month' => 2,
        'day' => 26,
        'weekday' => 'Thursday',
        'formatted' => '26 February 1987 (Thursday) (1987-02-26)',
    ],
    'age' => 38,
    'region' => [
        'code' => 78,
        'name' => 'Burgas',
        'range_start' => 44,
        'range_end' => 93,
    ],
    'birth_order' => 18,
    'zodiac' => [
        'name' => 'Pisces',
        'range' => '19 February - 20 March',
        'label' => 'Pisces (19 February - 20 March)',
    ],
]

Generate One EGN

All options are optional.

$egn = Egn::generateOne([
    'gender' => 'female', // male|female|m|f
    'year' => 1996,       // optional
    'month' => 8,         // optional
    'day' => 14,          // optional
    'region' => 22,       // optional, 0..99
]);

Generate Multiple EGNs

$egns = Egn::generate(50, [
    'month' => 2,
    'day' => 29,
]);

Use Exact Date

$egn = Egn::generateOne([
    'date' => '2004-06-12',
    'gender' => 'male',
]);

date accepts DateTimeInterface|string|null.

Generation Options Reference

• gender: male|female|m|f
• date: exact date as DateTimeInterface|string
• year: integer in configured range
• month: integer 1..12
• day: integer 1..31 (validated against month/year)
• region: integer 0..99

Notes:

• date takes precedence over year/month/day
• Invalid combinations (for example impossible date constraints) throw InvalidArgumentException

Region Mapping

The package resolves region names from the EGN serial (digits 7-9) using inclusive upper bounds.

API Reference

validate(string $egn): bool
parse(string $egn): ?array
details(string $egn, string $format = 'array', ?string $locale = null): array|object|collection|null
generateOne(array $options = []): string
generate(int $count = 1, array $options = []): array

Testing

composer test

Contributing

Contributions are welcome. Please open an issue or pull request with a clear description and test coverage for behavioral changes.

Security

If you discover a security issue, please report it privately to the maintainer before opening a public issue.

Related Website

• Check and generate valid Bulgarian EGN numbers

License

MIT License. See LICENSE.