rechtlogisch/steuernummer

Normalize, denormalize and validate German tax numbers (Steuernummer)

v1.0.0 2024-07-09 21:05 UTC

Requires

• php: ^8.1

Requires (Dev)

• laravel/pint: ^1.0
• pestphp/pest: ^2.20
• pestphp/pest-plugin-type-coverage: ^2.8
• phpstan/phpstan: ^1.11

MIT

• Krzysztof Tomasz Zembrowski

• validate
• normalize
• germany
• denormalize
• tax number
• rechtlogisch
• steuernummer

README

steuernummer

Normalize, denormalize and validate German tax numbers (Steuernummer)

Formats bidirectionally German tax numbers originating from tax office letters (German: Bescheidformat) or the ELSTER-Format (German: bundeseinheitliches ELSTER-Steuernummerformat) and validates it.

Based on the official ELSTER documentation (chapters: 3-7; as of 2024-06-17). Inspired by kontist/normalize-steuernummer and kontist/denormalize-steuernummer.

Hint: This package validates solely the syntax and check digit of the provided input. It does not confirm, that the provided Steuernummer was assigned to any entity. Please contact the responsible tax office in case of any doubts concerning the correctness of your Steuernummer.

Installation

You can install the package via composer:

composer require rechtlogisch/steuernummer

Usage

Normalize

normalizeSteuernummer('21/815/08150', 'BE'); // => '1121081508150'

or

use Rechtlogisch\Steuernummer\Normalize;

(new Normalize('21/815/08150', 'BE'))
    ->returnElsterSteuernummerOnly(); // => '1121081508150'

Hint: you can use run() instead, if you want more details.

Denormalize

denormalizeSteuernummer('1121081508150'); // => '21/815/08150'

or

use Rechtlogisch\Steuernummer\Denormalize;

(new Denormalize('1121081508150'))
    ->returnSteuernummerOnly(); // => '21/815/08150'

Hint: you can use run() instead, if you want more details.

Details

You can additionally control the result with setting returnWithFederalState: true. When set true information which federal state the Steuernummer origins from is being added to result.

denormalizeSteuernummer('1121081508150', returnWithFederalState: true);
// [
//   'steuernummer' => '21/815/08150',
//   'federalState' => 'BE',
// ]

or

use Rechtlogisch\Steuernummer\Denormalize;

(new Denormalize('1121081508150'))
    ->returnWithFederalState(); 
// [
//   'steuernummer' => '21/815/08150',
//   'federalState' => 'BE',
// ]

Hint: you can use run() instead, if you want even more details.

Validate

You can validate an input in the so called ELSTER-Steuernummerformat (13-digits):

isElsterSteuernummerValid('1121081508150'); // => true

or by providing the so called Bescheidformat (length varies) together with the federal state:

isSteuernummerValid('21/815/08150', 'BE'); // => true

Hint: Notice, that there are two functions isElsterSteuernummerValid() and isSteuernummerValid() depending on the format of your input.

Alternative

use Rechtlogisch\Steuernummer\Validate;

(new Validate('1121081508150'))
    ->run() // ValidationResult::class
    ->isValid(); // => true

The federal state is determined by the first digits of the ELSTER-Format, you can provide it as the second parameter to override the auto-determination:

use Rechtlogisch\Steuernummer\Validate;

(new Validate('1121081508150', 'BE'))
    ->run() // ValidationResult::class
    ->isValid(); // => true

Errors

You can get a list of errors explaining why the provided input is invalid. The run() method on each class returns a DTO with a getErrors() method.

Hint: The keys of getErrors() hold the stringified reference to the exception class. You can check for a particular error by comparing to the ::class constant. For example: Rechtlogisch\Steuernummer\Exceptions\InvalidElsterSteuernummerLength::class.

Validation errors

use Rechtlogisch\Steuernummer\Validate;

(new Validate('123456789012', 'BE'))
    ->run() // ValidationResult::class
    ->getErrors();
// [
//   'Rechtlogisch\Steuernummer\Exceptions\InvalidElsterSteuernummerLength'
//    => 'elsterSteuernummer must be 13 digits long. You provided: 12 digits.'
// ]

Normalization errors

use Rechtlogisch\Steuernummer\Normalize;

(new Normalize('123456789', 'BE'))
    ->run() // NormalizationResult::class
    ->getErrors();
// [
//   'Rechtlogisch\Steuernummer\Exceptions\InvalidSteuernummerLength'
//    => 'steuernummer for BE must contain exactly 10 digits. You provided: 9 digits.'
// ]

Denormalization errors

use Rechtlogisch\Steuernummer\Denormalize;

(new Denormalize('123456789012'))
    ->run() // DenormalizationResult::class
    ->getErrors();
// [
//   'Rechtlogisch\Steuernummer\Exceptions\InvalidElsterSteuernummerLength'
//    => 'elsterSteuernummer must be 13 digits long. You provided: 12 digits.'
// ]

Hint: All *Result::class extend the ResultDto.

Supported tax offices

By default, tax office codes (German: Bundesfinanzamtsnummer - short BUFA) included in the ELSTER ERiC libraries are supported by this package. Currently, based on ERiC 40.1.8. You'll find the list in src/Bufas.php.

The list includes test BUFAs, which are invalid in production. It is recommended to disable them in production with the following environment variable:

STEUERNUMMER_PRODUCTION=true

or in PHP:

putenv('STEUERNUMMER_PRODUCTION=true');

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Krzysztof Tomasz Zembrowski
• All Contributors

License

The MIT License (MIT). Please see License File for more information.