PHPackages                             bishopbd/aamva-parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. bishopbd/aamva-parser

ActiveLibrary

bishopbd/aamva-parser
=====================

Parses AAMVA driver's license and ID card PDF417 payloads into normalized and lossless structured data.

v0.0.1(1mo ago)0125↑266.7%MITPHPPHP ^8.4

Since Jul 16Pushed 1mo agoCompare

[ Source](https://github.com/bishop-bd/aamva-parser)[ Packagist](https://packagist.org/packages/bishopbd/aamva-parser)[ RSS](/packages/bishopbd-aamva-parser/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

aamva-parser
============

[](#aamva-parser)

Parse the machine-readable data from AAMVA-compliant driver's licenses and ID card PDF417 barcodes into a consistent associative array.

Requirements
------------

[](#requirements)

- PHP 8.4 or later

Installation
------------

[](#installation)

```
composer require bishopbd/aamva-parser
```

Usage
-----

[](#usage)

```
use AamvaParser\Parser;

$result = (new Parser())->parse($scannerData);

echo $result['first'];
echo $result['last'];
echo $result['address'];

$json = json_encode($result, JSON_THROW_ON_ERROR);
```

For complete data, including fields that are unknown to this library or specific to an issuing jurisdiction, use `parseDocument()`:

```
$document = (new Parser())->parseDocument($scannerData);

$normalized = $document->normalized(); // Same result as parse().
$allFields = $document->elements();     // Every designator and repeated value.
$documentNumber = $document->value('DAQ');
$metadata = $document->metadata();      // IIN, version/year, and subfile count.
$subfiles = $document->subfiles();      // Fields retain subfile provenance.
$warnings = $document->warnings();      // Non-fatal structural/version issues.
```

`ParsedDocument` is immutable and implements `JsonSerializable`. Unknown three-letter elements are preserved rather than discarded. `value()` returns the last occurrence for compatibility, while `values()` returns all repeated occurrences in source order.

### Scanner input formats

[](#scanner-input-formats)

`Parser::parse()` automatically accepts:

- Raw AAMVA text, including binary control separators.
- Space- or comma-separated hexadecimal bytes, such as `40 0A 1E 0D 41 4E 53 49 ...`.
- Standard padded or unpadded Base64 containing AAMVA data.
- Layered transport data, such as hex bytes that decode to a Base64 AAMVA payload.

Transport bytes before the `@` compliance indicator and control bytes after the last record are ignored. Conversion is also available directly:

```
use AamvaParser\DataHandler;

$handler = new DataHandler();
$rawFromHex = $handler->fromByteString($hexByteString);
$rawFromBase64 = $handler->base64Decode($base64String);
```

Explicit conversion methods throw `InvalidArgumentException` for malformed input. Parser auto-detection only decodes a value when its decoded content looks like AAMVA data, preventing ordinary scan text from being misinterpreted.

`parse()` always returns every normalized key. Missing optional data is an empty string:

```
[
    'first' => 'JANE',
    'last' => 'DOE',
    'mid' => 'QUINN',
    'address' => '123 FAKE ST',
    'address2' => '',
    'city' => 'EXAMPLETOWN',
    'state' => 'TX',
    'zip' => '750010123',
    'expMM' => '12',
    'expDD' => '31',
    'expYYYY' => '2030',
    'dobMM' => '07',
    'dobDD' => '15',
    'dobYYYY' => '1992',
    'fullEXP' => '20303112',
]
```

Names and addresses are mapped from `DAC`, `DCS`, `DAD`, `DAG`, `DAH`, `DAI`, `DAJ`, and `DAK`. Legacy `DAA`, `DAB`, and `DCT` name fields are supported as fallbacks. Expiration (`DBA`) and birth (`DBB`) dates support both `MMDDYYYY`and `YYYYMMDD`. To match the output contract above, `fullEXP` is `YYYYDDMM`.

The parser accepts compliant control-character separators as well as common scanner transformations such as CR/LF records, pipe-delimited records, a UTF-8 BOM, leading scanner text, omitted headers, and human-readable line formatting. It throws `InvalidArgumentException` when no AAMVA data elements can be found.

Compatibility scope
-------------------

[](#compatibility-scope)

The parser handles the AAMVA structure generically; this alone does not prove compatibility with every card issued by every jurisdiction. The auditable [DL/ID support matrix](docs/support-matrix.md) distinguishes synthetic structural tests from fixtures verified against issued cards. New approved fixtures placed under [`tests/Fixtures`](tests/Fixtures) are automatically run by PHPUnit. A state is not claimed as verified until current driver-license and identification-card fixtures satisfy that matrix's acceptance gate.

The generated suite exercises `DL` and `ID` subfiles for all 50 states plus District of Columbia and ANSI header versions `00` through `10` (the 2000 through 2025 standard generations). These are synthetic interoperability tests, not substitutes for authorized, de-identified samples from issuing agencies.

Standard
--------

[](#standard)

The header, subfile directory, and data element handling follow the [AAMVA DL/ID Card Design Standard 2025](https://www.aamva.org/getmedia/81af105d-8b1b-45e1-aa46-f1800a259ed1/AAMVADLIDCardDesignStandard2025.pdf), published by the [AAMVA Card Design Standard Subcommittee](https://www.aamva.org/drivers/subcommittees-working-groups/card-design-standard-subcommittee-be78411d579392b1eb755bb060492f3b).

Testing
-------

[](#testing)

```
composer test
```

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance90

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/801c04421d711504147a15ae03db738fdf80a32014cb56743b94534a17a5a970?d=identicon)[bishop-bd](/maintainers/bishop-bd)

---

Top Contributors

[![bishop-bd](https://avatars.githubusercontent.com/u/35353006?v=4)](https://github.com/bishop-bd "bishop-bd (4 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/bishopbd-aamva-parser/health.svg)

```
[![Health](https://phpackages.com/badges/bishopbd-aamva-parser/health.svg)](https://phpackages.com/packages/bishopbd-aamva-parser)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)