adawolfa/isdoc

ISDOC 解析器和生成器。

1.2.1 2023-08-18 12:14 UTC

This package is auto-updated.

Last update: 2024-09-18 14:50:35 UTC


README

这是一个用于解析和生成ISDOC文件的PHP库。

安装

composer require adawolfa/isdoc

读取文件

$manager = Adawolfa\ISDOC\Manager::create();
$invoice = $manager->reader->file('filename.isdoc');

print $invoice->id;

foreach ($invoice->invoiceLines as $invoiceLine) {
    print $invoiceLine->note->content;
}

默认情况下,文件将反序列化为 Adawolfa\ISDOC\Schema\Invoice。该命名空间中的所有代码都是自动从官方XSD模式生成的。您可以扩展基本的 Invoice 类并映射您或您供应商的扩展。

use Adawolfa\ISDOC\Map;

class MyInvoice extends Adawolfa\ISDOC\Schema\Invoice
{
    #[Map('Extensions')]
    private ?MyExtensions $extensions;
}

class MyExtensions
{
    #[Map('CustomElement')]
    private string $customElement;
}

$invoice = $manager->reader->file('filename.isdoc', MyInvoice::class);

写入文件

当创建ISDOC文件时,应使用装饰的 Adawolfa\ISDOC\Invoice 类,因为构造函数更合理,并具有合理的默认值。它还处理一些摘要字段。

$invoice = new ISDOC\Invoice(
    '12345',
    '00000000-0000-0000-0000-000000001234',
    DateTimeImmutable::createFromFormat('Y-m-d', '2021-08-16'),
    false,
    'CZK',
    new ISDOC\Schema\Invoice\AccountingSupplierParty(
        new ISDOC\Schema\Invoice\Party(
            new ISDOC\Schema\Invoice\PartyIdentification('12345678'),
            new ISDOC\Schema\Invoice\PartyName('Firma, a. s.'),
            new ISDOC\Schema\Invoice\PostalAddress(
                'Dlouhá',
                '1234',
                'Praha',
                '100 01',
                new ISDOC\Schema\Invoice\Country('CZ', 'Česká republika')
            )
        )
    )
);

$invoice->invoiceLines->add(
    new ISDOC\Schema\Invoice\InvoiceLine('1', '100.0', '121.0', '21.0', '100.0', '121.0',
        new ISDOC\Schema\Invoice\ClassifiedTaxCategory(
            '21',
            ISDOC\Schema\Invoice\ClassifiedTaxCategory::VAT_CALCULATION_METHOD_FROM_THE_TOP,
        ),
    )
);

$manager->writer->file($invoice, 'filename.isdoc');

ISDOCX

支持ISDOCX文件。可以使用.isdocx扩展名或在读取/写入时指定文件格式。

$invoice = $manager->reader->file('filename.isdocx', ISDOC\Schema\Invoice::class, $manager::FORMAT_ISDOCX);
$manager->writer->file('filename.isdocx', $manager::FORMAT_ISDOCX);

附件(即补充)默认支持。当生成ISDOCX文件时,请使用 Adawolfa\ISDOC\Invoice\Supplement

$supplement = Adawolfa\ISDOC\Invoice\Supplement::fromPath('attachment.pdf');
$invoice->supplementsList->add($supplement);

将自动计算和附加摘要(SHA1,目前不支持其他算法)。

读取时使用不同的子类

foreach ($invoice->supplementsList as $supplement) {

    if ($supplement instanceof Adawolfa\ISDOC\X\Supplement) {
        
        if (!$supplement->ok) {
            throw new Exception('Digest failed.');
        }
        
        $supplement->saveTo("supplements/{$supplement->filename}");
        
    }

}

常见问题解答

我有一个不符合规范的ISDOC文件,缺少一个必需的值。

您可能会遇到如下异常

Fatal error: Uncaught Adawolfa\ISDOC\Data\ValueException: Value VATApplicable is missing.

默认情况下,解码器会填充(即解码和分配)所有声明的属性,除非它们在ISDOC文件中不存在且有默认值。某些值始终应该存在,但有时由于发行方的实现不完整,它们可能不存在。

绕过此问题的方法之一是启用宽松的填充模式,这将导致填充器简单地跳过这些属性。

$manager = Adawolfa\ISDOC\Manager::create($skipMissingPrimitiveValuesHydration = true);
$invoice = $manager->reader->file('filename.isdoc');

但是请注意,这样的对象可能具有未初始化的属性,这可能会在以后引起问题。

开发

make composer-install # run composer install (Docker)
make composer-update # run composer update (Docker)
make generate-schema # generate new schema after updating xsd file (Docker)
make run-tests # run tests (Docker)