v2.0.0 — PHP 8.2, check-digit validation, typed API, and new formats

[rakibdevs]

Overview

Modernizes the package to PHP 8.2, fixes several correctness/robustness bugs, adds a real test suite (there was none), and introduces MRZ check-digit validation plus a typed API. This is a breaking release (PHP floor raised, new output keys), so it targets v2.0.0.

▎ ℹ️ MrzParser::parse() keeps returning the same associative array — all changes to it are additive keys. No existing key was renamed or removed.

Why

• CI tested only PHP 8.0 and the "test suite" was a placeholder asserting true — zero real coverage.
• The parser extracted data but never verified MRZ check digits, so corrupt/typo'd input was returned silently as valid.
• Real-world input broke it: \r\n (Windows/OCR) inflated line length and failed validation; impossible dates (e.g. Feb 30) silently rolled over; a date of birth could resolve to the future.
• A PHP 8.4 implicit-nullable deprecation was already present.

Breaking changes

• Minimum PHP is now 8.2 (was 8.0).
• parse() returns additional keys: issuer_code, nationality_code, sex, optional_data, valid, validation, raw.
• Enums\DocumentType is now a backed enum instead of an abstract class with constants.

Highlights

Check-digit validation

Implements the ICAO 9303 7‑3‑1 weighted checksum (Support\CheckDigit). Every result now carries an overall valid flag and a per-field validation map (document number, date of birth, date of expiry, personal number, and composite). Verified against the ICAO 9303 specimens.

Typed API & ergonomics

• MrzParser::read() → MrzResult value object (typed props, dateOfBirthAsDate(), dateOfExpiryAsDate(), isExpired(), fullName(), toArray()).
• MrzParser::tryParse() / tryRead() → null instead of throwing on invalid input.
• Strict mode: parse($text, strict: true) throws InvalidChecksumException when a check digit fails.

New formats & helpers

• French national ID (legacy 2×36 Carte Nationale d'Identité) — bespoke layout, no expiry encoded. Offsets independently corroborated against an authoritative parser; the specimen's three check digits (incl. the distinctive continuous cross-line composite) all validate.
• Name transliteration (Support\Transliterator): fromLatin('Müller') → 'MUELLER' and matches() to compare a visual-zone name against an MRZ name.

Robustness fixes

• Central input normalization (MrzNormalizer): CRLF/CR → LF, trim, drop blank lines — Windows/OCR input now parses.
• Strict date validation (rejects impossible dates); date of birth is century-corrected to the past.
• Fixed the PHP 8.4 implicit-nullable deprecation and guarded against substr(null, …).
• Consistent trailing-filler trimming for given names across all document types.

Modernization

declare(strict_types=1) throughout, typed properties, match-based adapter selection, cached country lookup table.

Laravel

Auto-discovered MrzParserServiceProvider and a ValidMrz validation rule (with optional strict mode). Requires illuminate/support (declared as a suggest + dev dependency).

Tooling & CI

• Pest 1 → Pest 3; phpunit.xml.dist migrated to the PHPUnit 11 schema.
• CI matrix now PHP 8.2 / 8.3 / 8.4 / 8.5; actions/checkout@v4.
• README badges (tests, PHP version, downloads, license).

Testing

• 99 tests / 230 assertions, ~99% line coverage (the only uncovered lines are two unreachable defensive branches).
• Covers: every document type happy-path, validation boundaries and invalid-input cases, CRLF regression, check-digit mutation/tamper regressions, strict mode, the DTO, transliteration, and the Laravel rule.
• composer validate ✅ · php -l clean ✅ · php-cs-fixer 0 fixes ✅ · no PHP 8.4 deprecations ✅.

Notes for reviewers

• The French ID document number and line‑1 admin block are exposed as opaque identifiers — sources disagree on their internal sub-structure and no check digit validates it, so parsing does not depend on it.
• Transliteration is deterministic Latin → MRZ only; the reverse is inherently ambiguous (OE may be Ö or a literal OE), so matches() covers the real use case rather than faking a lossy reverse.