A PHP function to parse a Federal Firearms License (FFL) number

parseFFL.php

/**
 * Parses the FFL number and extracts relevant information.
 *
 * @param string $fflNumber The FFL number to parse.
 * @return array An array containing the parsed FFL information or an error object.
 *               If parsing is successful, the array will have the following keys:
 *               - ffl_number: The full FFL number.
 *               - region: The region of the FFL.
 *               - irs_district: The IRS district of the FFL.
 *               - fips_code: The FIPS code of the FFL.
 *               - license_type: The type of license.
 *               - expiration_date: The expiration date of the FFL.
 *               - unique_code: The unique code of the FFL.
 *               If any information cannot be calculated, an error object will be returned.
 *               The error object will have the following keys:
 *               - error: A descriptive error message.
 *               - ffl_number: The full FFL number (optional, if available).
 *
 * @author Stephen Feather
 * @copyright Copyright (c) 2023
 */
function parseFFLNumber($fflNumber) {
    $regions = array(
        1 => 'Region 1: Southeast',
        3 => 'Region 3: Midwest',
        4 => 'Region 4: Central',
        5 => 'Region 5: Southwest',
        6 => 'Region 6: North Atlantic',
        8 => 'Region 8: Mid Atlantic',
        9 => 'Region 9: Western'
    );

    $months = array(
        'A' => 'January',
        'B' => 'February',
        'C' => 'March',
        'D' => 'April',
        'E' => 'May',
        'F' => 'June',
        'G' => 'July',
        'H' => 'August',
        'J' => 'September',
        'K' => 'October',
        'L' => 'November',
        'M' => 'December'
    );

    $licenseTypes = array(
        1 => 'Type 01: Firearm Dealer/Gunsmith',
        2 => 'Type 02: Pawnbroker',
        3 => 'Type 03: Collector',
        6 => 'Type 06: Manufacturer of Ammunition',
        7 => 'Type 07: Manufacturer of Firearms',
        8 => 'Type 08: Importer of Firearms',
        9 => 'Type 09: Dealer of "Destructive Devices"',
        10 => 'Type 10: Manufacturer of "Destructive Devices"',
        11 => 'Type 11: Importer of "Destructive Devices"'
    );

    $fflInfo = array();

    // First section: FFL Number
    $fflInfo['ffl_number'] = $fflNumber;

    // Second section: Region
    $regionDigit = intval($fflNumber[0]);
    if (isset($regions[$regionDigit])) {
        $fflInfo['region'] = $regions[$regionDigit];
    } else {
        return [
            'error' => 'Invalid Region',
            'ffl_number' => $fflNumber
        ];
    }

    // Third section: IRS district
    $fflInfo['irs_district'] = intval(substr($fflNumber, 2, 2));

    // Fourth section: FIPS code
    $fflInfo['fips_code'] = substr($fflNumber, 5, 3);

    // Fifth section: License type
    $licenseTypeDigit = intval(substr($fflNumber, 9, 2));
    if (isset($licenseTypes[$licenseTypeDigit])) {
        $fflInfo['license_type'] = $licenseTypes[$licenseTypeDigit];
    } else {
        return [
            'error' => 'Invalid License Type',
            'ffl_number' => $fflNumber
        ];
    }

    // Sixth section: Expiration date
    $yearDigit = intval($fflNumber[12]);
    $monthLetter = $fflNumber[13];
    $currentYear = intval(date('Y'));
    $yearPrefix = $currentYear - ($currentYear % 10);
    $year = $yearPrefix + $yearDigit;
    if (isset($months[$monthLetter])) {
        $month = $months[$monthLetter];
    } else {
        return [
            'error' => 'Invalid Expiration Month',
            'ffl_number' => $fflNumber
        ];
    }
    $fflInfo['expiration_date'] = $month . ' ' . $year;

    // Seventh section: Unique code
    $fflInfo['unique_code'] = substr($fflNumber, 15);

    return $fflInfo;
}