Skip to content

Validation

Jump to bottom
horstoeko edited this page May 7, 2024 · 21 revisions

Table of contents

Different mechanisms

There are generally two classes in this library that can validate documents:

  • A pure schema validation against the schema (XSD) by the class ZugferdXsdValidator.
  • A complete validation including business rules by the class ZugferdKositValidator. This class relies on an external tool from the Coordination Office for IT Standards (KoSIT) (German institution of the Federal Republic of Germany) to perform the validation. The validation currently only takes into account validation in accordance with EN16931 and the German CIUS XRechnung. For more details see KoSIT Validator on GitHub. At present, this feature is still to be considered experimental.

Pure XSD Validation

If only a pure validation against the XSD schema is required, then the class ZugferdXsdValidator is completely sufficient. A handling description is available in the form of an example implementation in the examples folder under XsdValidator.php.

Using the class ZugferdXsdValidator is very simple: When a new instance of this class is created, the constructor expects a parameter of the type ZugferdDocument. This makes it possible to check/validate both incoming documents from ZugferdDocumentReader and ZugferdDocumentPdfReader as well as outgoing documents from ZugferdDocumentBuilder:

From ZugferdDocumentReader:

$document = ZugferdDocumentReader::readAndGuessFromFile(dirname(__FILE__) . "/incoming.xml");

$xsdValidator = new ZugferdXsdValidator($document);
$xsdValidator->validate();

From ZugferdDocumentPdfReader:

$document = ZugferdDocumentPdfReader::readAndGuessFromFile(dirname(__FILE__) . "/incoming.pdf");

$xsdValidator = new ZugferdXsdValidator($document);
$xsdValidator->validate();

From ZugferdDocumentBuilder

$document = ZugferdDocumentBuilder::CreateNew(ZugferdProfiles::PROFILE_EN16931);
$document
    ->setDocumentInformation("471102", "380", \DateTime::createFromFormat("Ymd", "20180305"), "EUR")
    .....

$xsdValidator = new ZugferdXsdValidator($document);
$xsdValidator->validate();

After executing the validate method, further methods are available to determine any validation errors:

Method Description
$xsdValidator->validationPased Returns true or false. True if the validation has been passed successfully
$xsdValidator->validationFailed Returns true or false. True if the validation failed
$xsdValidator->validationErrors Returns an array of strings. Each array element contains a validation error

Validation using the Kosit Validation tool

General

Important note: At present, this feature is still to be considered experimental.

For a more extensive validation, use the class ZugferdKositValidator. Please note that this class requires a functioning and complete JAVA installation (e.g. openjdk-11-jre-headless for Linux operating systems) to perform the validation correctly, as the external tool (KoSIT-Validator) is a pure JAVA application that is called by the class. A handling description is also available in the form of an example implementation in the examples folder under KositValidator.php.

As with the ZugferdXsdValidator, this class can receive several different input instances: ZugferdDocumentReader, ZugferdDocumentPdfReader and ZugferdDocumentBuilder.

Change the version of the validator application and the used scenarios

By default, the class ZugferdKositValidator uses version 1.5.0 of the KoSIT validator and the validation rule from 15.11.2023. You can also change the version to be used by changing the download URL:

$kositValidator = new ZugferdKositValidator()
$kositValidator->setValidatorDownloadUrl('https://github.com/itplr-kosit/validator/releases/download/v1.4.2/validator-1.4.2-distribution.zip');
$kositValidator->setValidatorScenarioDownloadUrl('https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/release-2023-07-31/validator-configuration-xrechnung_3.0.0_2023-07-31.zip');

After changing the download URL of the JAVA application, it may also be necessary to change the file name of the JAR file to be executed:

$kositValidator->setValidatorAppJarFilename('validationtool-1.4.2-java8-standalone.jar');

Methods to control behavior

Overall, there are different methods to change the behavior of the class ZugferdKositValidator:

Method Description Default
setBaseDirectory Sets the temporary directory where all the needed files are downloaded and unpacked to sys_get_temp_dir()
setDocument Sets a (different) ZugferdDocument-Instance to do the validation for null
setValidatorDownloadUrl Sets a different URL (a different version) where the Release of an KoSIT-Validator-Application is located https://github.com/itplr-kosit/validator/releases/download/v1.5.0/validator-1.5.0-distribution.zip
setValidatorScenarioDownloadUrl Sets a different URL where the release of validation rules is located https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/release-2023-11-15/validator-configuration-xrechnung_3.0.1_2023-11-15.zip
disableCleanup Disable cleaning the BaseDirectory (see setBaseDirectory)
enableCleanup Enable cleaning the BaseDirectory (see setBaseDirectory)

Run Validation

To start a validation, use the validate method

$document = ZugferdDocumentPdfReader::readAndGuessFromFile(dirname(__FILE__) . "/invoice.pdf");

$kositValidator = new ZugferdKositValidator($document)
$kositValidator->validate();

or

$document = ZugferdDocumentPdfReader::readAndGuessFromFile(dirname(__FILE__) . "/invoice.pdf");

$kositValidator = new ZugferdKositValidator()
$kositValidator->setDocument($document)->validate();

Obtain process errors

Process errors can be of various types. For example, the download or unpacking of one of the JAVA validation applications fails.

Method Description
getProcessErrors Returns process errors as an string array.
hasNoProcessErrors Returns true if there are no process errors.
hasProcessErrors Returns true if there are process errors.

Obtain validation errors/warnings/information

To obtain the validation results, there are various methods that provide you with information about the validation result:

Method Description
getValidationErrors Returns a string array with "real" validation errors. Each item contains one validation error
hasNoValidationErrors Returns true if there are no "real" validation errors.
hasValidationErrors Returns true if there are "real" validation errors.
getValidationWarnings Returns a string array with validation warnings. Each item contains one validation warning
hasNoValidationWarnings Returns true if there are no validation warnings.
hasValidationWarnings Returns true if there are validation warnings.
getValidationInformation Returns a string array with validation information. Each item contains one validation information
hasNoValidationInformation Returns true if there are no validation information.
hasValidationInformation Returns true if there are validation information.

Chained validation

Sometimes it is necessary to validate several documents in succession without having to download the Java application and the validation scenarios again each time. Chained validation" can be used here. Here is a small example:

$document1 = ZugferdDocumentPdfReader::readAndGuessFromFile(dirname(__FILE__) . "/invoice_1.pdf");
$document2 = ZugferdDocumentPdfReader::readAndGuessFromFile(dirname(__FILE__) . "/invoice_2.pdf");
$document3 = ZugferdDocumentPdfReader::readAndGuessFromFile(dirname(__FILE__) . "/invoice_3.pdf");

$kositValidator = new ZugferdKositValidator();

if ($kositValidator->disableCleanup()->setDocument($document1)->validate()->hasValidationErrors()) {
    // Handle validation errors
}

if ($kositValidator->setDocument($document2)->validate()->hasValidationErrors()) {
    // Handle validation errors
}

if ($kositValidator->enableCleanup()->setDocument($document3)->validate()->hasValidationErrors()) {
    // Handle validation errors
}

Table of contents

Clone this wiki locally