Validation

Table of contents

• Different mechanisms
  • Pure XSD Validation
  • Validation using the KoSIT Validation tool
    • General
    • Change the version of the validator application and the used scenarios
    • Methods to control behavior
    • Run Validation
    • Obtain process errors
    • Obtain validation errors/warnings/information
    • Chained validation
    • Remote validation

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

Caution

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
}

Remote validation

Since version 1.0.96 it is possible to transfer the validation of a document via HTTP request to a running instance of the KoSIT validator. The validator must be running in daemon mode. Further information can be found at https://github.com/itplr-kosit/validator/blob/main/docs/daemon.md

The following additional configuration options are available:

Method	Description
enableRemoteMode	Activates the communication via HTTP to a running validator instance. No files are downloaded from the itplr-kosit/validator-Repository
disableRemoteMode	Deactivates the communication via HTTP to a running validator instance
setRemoteModeHost	This method takes the hostname (including domain) or the ip address where the Validator is running in daemon-mode
setRemoteModePort	This method takes the port of the host where the Validator is running in daemon-mode

The following example is intended to illustrate the use of the methods just mentioned:

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

$kositValidator = new ZugferdKositValidator($document)
$kositValidator
  ->enableRemoteMode()
  ->setRemoteModeHost('validator.somedomain.com')
  ->setRemoteModePort(8081)
  ->validate();

if ($kositValidator->hasValidationErrors()) {
    // Do something when validation has failed
}