README

Taxpayer Identification Number (TIN) Validator

Description

A library to validate TIN numbers for individuals. This is based on a Java library, this is why the code does not reflect best practices in PHP (yet).

Supported countries:

• Austria (AT)
• Belgium (BE)
• Bulgaria (BG)
• Croatia (HR)
• Cyprus (CY)
• Czech Republic (CZ)
• Denmark (DK)
• Estonia (EE)
• Finland (FI)
• France (FR)
• Germany (DE)
• Greece (GR) - only size
• Hungary (HU)
• Ireland (IE)
• Italy (IT)
• Latvia (LV) - no check digit
• Lithuania (LT)
• Luxembourg (LU)
• Malta (MT) - no check digit
• Netherlands (NL)
• Poland (PL)
• Portugal (PT)
• Romania (RO) - no check digit
• Slovakia (SK)
• Slovenia (SI)
• Spain (ES)
• Sweden (SE)
• United Kingdom (UK) - only structure

If your country is not there, feel free to open an issue with your country code, and a link to the specification. Ideally, you can provide a pull request with the algorithm and the tests.

Requirements

• PHP >= 8.1

Usage & API

To simply check the validity of a TIN number:

<?php

include __DIR__ . '/vendor/autoload.php';

use loophp\Tin\TIN;

$bool = TIN::fromSlug('be71102512345')->isValid();

If you want to get the reason why a number is invalid, you can use

<?php

include __DIR__ . '/vendor/autoload.php';

use loophp\Tin\TIN;
use loophp\Tin\Exception\TINException;

try {
    TIN::fromSlug('be71102512345')->check();
} catch (TINException $e) {
    // do something with the exception.
}

Strict Mode

If you want to use a stricter method (without normalizing the TIN number, that is, using the raw TIN number), use the strict parameter in the check or isValid functions as shown below (Introduced in #39). By default, it is set to false.

TIN::fromSlug('be7110.2512345')->check(); // Not strict
TIN::fromSlug('be7110.2512345')->check(strict: false); // Not strict
TIN::fromSlug('be7110.2512345')->check(true); // Strict
TIN::fromSlug('be7110.2512345')->check(strict: true); // Strict

Installation

composer require loophp/tin

Code quality, tests and benchmarks

Every time changes are introduced into the library, Github run the tests and the benchmarks.

The library has tests written with PHPSpec. Feel free to check them out in the spec directory. Run composer phpspec to trigger the tests.

Before each commit some inspections are executed with GrumPHP, run ./vendor/bin/grumphp run to check manually.

PHPInfection is used to ensure that your code is properly tested, run composer infection to test your code.

Links

• European Commission TIN service
• TIN Algorithms - Public - Functional Specification
• Taxpayer Identification Number

Authors

• Thomas Portelange
• Pol Dellaiera

Contributing

We warmly welcome your contributions by submitting pull requests. Our team is highly responsive and will gladly guide you through the entire process, from the initial submission to the final resolution.

If, for any reason, you are unable to contribute directly to the code but still wish to support our efforts, consider sponsoring us. This is a reliable and meaningful way to express your appreciation for the countless hours we've dedicated to this project.

Support our contributors by sponsoring them on Github.