
Tax Audit Export for Laravel
Writes the data an application hands over to a tax audit in the form the German tax authority reads: a CSV file for each table, an index.xml after the description standard for the handing over of data (an annex to the GoBD), and the document type definition gdpdu-01-09-2004.dtd beside it. The same format carries the DSFinV-K export of a cash register, whose tables are described without a key. A reader opens such an export through its index.xml alone, and a validator checks an index.xml against the definition in a test suite.

The same files as text, with the index.xml cut down to the part that describes the columns of the invoices:
invoice_number,customer_number,gross_amount
"I-1","C-1",99.90
customer_number,name
"C-1","Erika Mustermann"
<VariableLength>
<ColumnDelimiter>,</ColumnDelimiter>
<RecordDelimiter>
</RecordDelimiter>
<TextEncapsulator>"</TextEncapsulator>
<VariablePrimaryKey>
<Name>invoice_number</Name>
<Description>Number of the invoice</Description>
<AlphaNumeric/>
<MaxLength>30</MaxLength>
</VariablePrimaryKey>
<VariableColumn>
<Name>customer_number</Name>
<Description>Number of the customer</Description>
<AlphaNumeric/>
<MaxLength>20</MaxLength>
</VariableColumn>
<VariableColumn>
<Name>gross_amount</Name>
<Description>Gross amount in euros</Description>
<Numeric>
<Accuracy>2</Accuracy>
</Numeric>
</VariableColumn>
<ForeignKey>
<Name>customer_number</Name>
<References>Customers</References>
</ForeignKey>
</VariableLength>
Installation
composer require pushery/tax-audit-export-for-laravel
The service provider is registered automatically through package discovery.
It needs PHP's dom, libxml and mbstring extensions, which a standard PHP build carries, and no database: the package keeps no table and writes files from the rows your application hands it.
Writing an export
Describe each table with its file, its name, a description and its columns. The first column is the key of the table, unless the table is built without one, which a section below shows. A table that names a record of another table carries that table's key column under the same name and lists the table in its references.
use Pushery\TaxAuditExport\Column;
use Pushery\TaxAuditExport\ExportSettings;
use Pushery\TaxAuditExport\Table;
$customers = new Table('customers.csv', 'Customers', 'The customers of the period', [
Column::text('customer_number', 'Number of the customer', 20),
Column::text('name', 'Name of the customer'),
]);
$invoices = new Table('invoices.csv', 'Invoices', 'The invoices of the period', [
Column::text('invoice_number', 'Number of the invoice', 30),
Column::text('customer_number', 'Number of the customer', 20),
Column::numeric('gross_amount', 'Gross amount in euros', 2),
], ['Customers']);
app(ExportSettings::class)->export()
->add($customers, [
['customer_number' => 'C-1', 'name' => 'Erika Mustermann'],
])
->add($invoices, [
['invoice_number' => 'I-1', 'customer_number' => 'C-1', 'gross_amount' => '99.90'],
])
->writeTo(storage_path('app/tax-audit/2025'));
The directory then holds customers.csv, invoices.csv, gdpdu-01-09-2004.dtd and index.xml. The rows of a table may come from any iterable of arrays keyed by column name, and each record is written as it arrives. So a table larger than the memory of the process can be exported from a source that loads it in chunks, such as lazyById() on a query. The example below reads the customers a thousand at a time and writes them into a directory of their own:
use Illuminate\Support\Facades\DB;
use Pushery\TaxAuditExport\ExportSettings;
$rows = DB::table('customers')
->select(['id', 'customer_number', 'name'])
->lazyById(1000)
->map(fn (object $row): array => [
'customer_number' => $row->customer_number,
'name' => $row->name,
]);
app(ExportSettings::class)->export()
->add($customers, $rows)
->writeTo(storage_path('app/tax-audit/2025-customers'));
The query selects the id, because lazyById() starts each chunk after the last id of the chunk before. A row of the query arrives as an object, and map() hands it over as an array that names the columns of the table, since the export takes arrays. For a model, lazyById(1000) with map(fn (Customer $customer): array => $customer->only(['customer_number', 'name'])) does the same. A query's cursor() is no such source: it yields objects, and the PDO driver keeps its whole result in a buffer, so the memory runs out all the same, as the Laravel documentation warns.
An export of a large table can run longer than a web request is allowed to take. Start it from a queued job or an Artisan command.
An export started from ExportSettings names the data supplier of the configuration, which the environment variables under Configuration below set. An export built as new Export(new DataSupplier('Example GmbH', 'Berlin', 'Fiscal year 2025')) names the supplier it is handed and reads no configuration.
ExportSettings reads the configuration the first time a request or a queued job resolves it, and keeps it until that request or job ends. Under Octane and in a long-running queue worker the next request or job reads the configuration again, so a supplier set for one request or job, one per tenant for example, is the one its export names. Set it before the settings are first resolved in that request or job.
writeTo() builds the index.xml before it writes the first file. A definition the description cannot carry is refused with an InvalidDefinition that names the table and the field, and the directory stays as it was. That includes two tables written to one file, and a table written to index.xml or gdpdu-01-09-2004.dtd, the two files the export writes itself. File names are compared without the case of their letters, because a file system may not tell a.csv from A.csv.
A directory that already holds an index.xml is refused with an UnwritableExport that names it, so an export is never written over another one. The same exception names a directory or a file the export cannot create or write, such as one it has no permission for, or the file of a table that a full disk or an exhausted quota stops partway, so a write that fails never arrives as the reader's UnreadableExport.
A table without a key
A table built with keyed: false has no key, and the index.xml names each of its columns as a plain column (VariableColumn). That is how the DSFinV-K describes its tables: their first column, Z_KASSE_ID, names the cash register and repeats in every record of one, so it is no key. The closings of a cash register, with the first three columns of the DSFinV-K table:
use Pushery\TaxAuditExport\Column;
use Pushery\TaxAuditExport\Table;
$closings = new Table('cashpointclosing.csv', 'Stamm_Abschluss', 'The closings of the cash register', [
Column::text('Z_KASSE_ID', 'ID of the cash register', 50),
Column::text('Z_ERSTELLUNG', 'Time of the closing', 30),
Column::numeric('Z_NR', 'Number of the closing'),
], keyed: false);
No table can reference a table without a key, because a ForeignKey names the key of the table it references: the export refuses such a reference with an InvalidDefinition that names both tables. A table without a key may itself reference a table that has one. The reader reads such a table back without a key as well: its keyed is false, and its key() returns null.
Columns and types
| Column | Written as | In the index.xml |
|---|---|---|
Column:: | between double quotes | AlphaNumeric |
Column:: | between double quotes, at most 40 characters | AlphaNumeric with MaxLength 40 |
Column:: | without quotes, a whole number | Numeric |
Column:: | without quotes, at most two decimals | Numeric with Accuracy 2 |
A number is written with a point before its decimals and without grouping. Pass it as an integer, as a string such as '1250.00', or as a float when its column names an accuracy. A string with a comma, with grouping or with a line break is refused: the description states the point, and a line feed ends the record. A string with more decimals than the accuracy of its column is refused too, because the description standard leaves open what an import makes of them. A column that names no accuracy holds whole numbers, since the standard reads it as an accuracy of 0, so '1250.00' needs a column with an accuracy of at least 2.
A text stands as given, its first character included, so the value in the file is the value of the original. A line break in a text becomes a space, because an import that follows the index.xml reads a line feed as the end of a record wherever it stands. A double quote in a text is doubled. A text longer than the greatest length of its column is refused, because an import may size the column by MaxLength instead of reading the file. The length counts characters, not bytes, so Größe is five characters long.
The values are written unchanged for the tax authority, so a text may begin with =, +, -, @ or a tab, which a spreadsheet takes for the start of a formula. Open the files through an import that follows the index.xml and reads such a column as text, never directly in a spreadsheet.
A column name stands in the header line without quotes, so it may hold neither a comma, nor a double quote, nor a line break. Nor may it be a whole number such as 2024 or -1, since a row names its values by column and PHP keeps such an array key as an integer, not as the name. A name such as year_2024 is accepted.
A value is checked as its record is written, so a refused value stops the export partway. writeTo() then removes the files it wrote and the directories it created before it throws the InvalidDefinition, so the directory is as it was and the next attempt can write into it. It does the same when a write fails or the rows themselves throw, and it leaves every file it did not create where it is.
The format of the files
Every file is written in one format, and the index.xml states it for every table: UTF-8, a comma between the fields, a double quote around a text, a line feed after every record, a point as the decimal symbol, a comma as the grouping symbol, and a header line an import skips (Range from the second record).
The document type definition
gdpdu-01-09-2004.dtd ships byte for byte as the BZSt publishes it in the package of the DSFinV-K 2.4, its CRLF line ends included. Its SHA-256 is af3d4c5a19e991f2d8c53995bc708680bbd7ff9326fde539c55b7e2c63f848a2, which Pushery\TaxAuditExport\Dtd::SHA256 names. Every index.xml declares it, and the export writes it beside the index.xml.
Reading an export
use Pushery\TaxAuditExport\Reader;
$reader = Reader::open(storage_path('app/tax-audit/2025'));
foreach ($reader->tables() as $table) {
foreach ($reader->rows($table->name) as $record) {
// $record holds the value of each column under its name, as text.
}
}
The reader takes the tables, their columns and types from the index.xml, never from the classes that wrote it, and from it as well the column delimiter, the text encapsulator, the record delimiter, the first record and the encoding of each file. So reading an export back in a test proves what its description says of them. Records are split at a line feed, a carriage return before it dropped. A value comes back as the text the file holds, so the reader needs neither the decimal nor the grouping symbol, and it does not read SkipNumBytes. A record whose fields differ in number from the columns of its table is refused with an UnreadableExport that names the file and the record. A table is read by its name: a description that names two tables alike is refused when the reader opens it, and rows() refuses a name the description does not know.
An index.xml the reader cannot read is refused with an UnreadableExport that names it and the reason. That includes an empty file, a column delimiter or a text encapsulator that is not a single byte (§ takes two in UTF-8), a record delimiter that is neither a line feed nor a carriage return and a line feed, a table of fixed length, and a table or a column the export would refuse to write, such as a file name with a space or an umlaut, a column name with a comma, or a greatest length of 0.
For an export written somewhere else, the reader holds three limits from the configuration: the largest index.xml it parses, the longest record it takes, and the encodings a table may declare. A larger index.xml is refused before it is read whole, with an UnreadableExport that names the limit. A record is measured in bytes without its line end, a line feed or a carriage return and a line feed, and takes the memory of its own length whatever the limit. UTF8 is read as it stands, and ANSI is converted from Windows-1252. The list narrows these two and adds none: a table in OEM, UTF16, UTF7 or Macintosh is refused even where the list names it. Resolve Pushery\TaxAuditExport\ExportSettings from the container to start a reader or an export with the configured values. The example below writes the customers of the first example once more, into a directory of their own, since an export is never written over another one:
use Pushery\TaxAuditExport\ExportSettings;
$settings = app(ExportSettings::class);
$rows = [['customer_number' => 'C-2', 'name' => 'Max Mustermann']];
$directory = storage_path('app/tax-audit/2025-settings');
$settings->export()->add($customers, $rows)->writeTo($directory);
$reader = $settings->reader($directory);
Testing
Pushery\TaxAuditExport\Testing\IndexValidator validates an index.xml against the definition and returns the messages of every place it departs from it. A test writes the export into a directory of its own and validates what it wrote:
use Illuminate\Support\Facades\Storage;
use Pushery\TaxAuditExport\Column;
use Pushery\TaxAuditExport\DataSupplier;
use Pushery\TaxAuditExport\Export;
use Pushery\TaxAuditExport\Table;
use Pushery\TaxAuditExport\Testing\IndexValidator;
it('writes an index.xml the definition accepts', function () {
$directory = Storage::fake('local')->path('tax-audit');
$customers = new Table('customers.csv', 'Customers', 'The customers of the period', [
Column::text('customer_number', 'Number of the customer', 20),
]);
(new Export(new DataSupplier('Example GmbH')))
->add($customers, [['customer_number' => 'C-1']])
->writeTo($directory);
expect(IndexValidator::errors(file_get_contents($directory.'/index.xml')))->toBe([]);
});
libxml refuses the content model the definition gives Media as not deterministic. The validator therefore reads the definition with an equivalent model that accepts the same documents. The export always ships the definition unchanged.
Configuration
Publish the configuration file, where every option is documented inline:
php artisan vendor:publish --tag=tax-audit-export-config
| Tag | Publishes |
|---|---|
tax-audit-export | everything below, in one command |
tax-audit-export-config | the configuration file |
tax-audit-export-lang | the translation files |
A setting that reads an environment variable changes without publishing the file:
| Environment variable | Setting | Default |
|---|---|---|
TAX_ | tax-audit-export. | the value of APP_NAME, also for an empty value |
TAX_ | tax-audit-export. | empty |
TAX_ | tax-audit-export. | empty |
TAX_ | tax-audit-export. | 1048576 (1 MiB), also for a value below 1024 |
TAX_ | tax-audit-export. | 8388608 (8 MiB), also for a value below 1024 |
What the package does not do
It does not decide which data an audit asks for, how long it must be kept, or which tables a business has to hand over. It writes and reads the files of the tables an application describes.