Quittio 0.3 API

Quittio
in package

FinalYes

Entry point without Laravel:

$quittio = Quittio::create(Config::fromArray([...]), [new CountryDE]); $result = $quittio->make($invoice)->format('zugferd')->render();

Every run calculates the data, chooses format and profile, validates, writes the XML, renders the template and produces the PDF/A with the embedded XML.

Table of Contents

Constants

DEFAULT_PROFILE  : string = 'en16931'
Profile when neither the call, the configuration nor the format names one.

Methods

__construct()  : mixed
addSerializer()  : self
Writes the XML of the serializer's syntax with $serializer from now on (replaces the serializer of that syntax). Changes this instance.
addValidator()  : self
Runs $driver in every validation after the drivers added before. Changes this instance.
calculator()  : TotalsCalculator
The calculator of the render runs, cancellations and the reader.
cancellation()  : InvoiceBuilder
Builder for the cancellation of an issued invoice. The sign strategy comes from the argument, the configuration or the country pack (in this order).
check()  : ValidationResult
Validates like a render run, without template and PDF; see prepare().
clearValidators()  : self
Removes every validation driver, e.g. before adding a custom set. Changes this instance.
config()  : Config
The configuration of this instance.
configureRules()  : self
Switches PHP rules off, changes the severity of their findings or replaces them, by rule code (see RuleOverrides); replaces the overrides of every PHP rules driver. Changes this instance.
countries()  : CountryRegistry
The registered country packs.
create()  : self
Instance with default registries, the configured validators and the given country packs.
document()  : PendingDocument
Starts the render call of a quote, order confirmation, delivery note, proforma invoice, payment reminder or account statement.
edit()  : InvoiceBuilder
Builder that continues existing invoice data, e.g. to correct a draft or an invoice read from XML: like InvoiceBuilder::from(), but the declared amounts are compared with the calculator of this instance.
formats()  : FormatRegistry
The output formats (zugferd, xrechnung-cii, ubl, pdf, html, json …).
make()  : PendingInvoice
Starts a render call: format(), profile(), locale() … and render(). A builder is built and a model converted (ProvidesInvoiceData) at once.
onMandatoryFieldsMissing()  : self
Called when a template omits mandatory values, in every guard mode except "off".
onResetState()  : void
Registers process-wide state of an extension with resetState(). A second registration under the same key replaces the first.
prepare()  : PreparedInvoice
Calculates and validates like a render run (without template and PDF) and returns the calculated data with the chosen formats, profiles, country packs and locale.
profiles()  : ProfileRegistry
The registered profiles, those of the country packs included.
read()  : ReadResult
Reads an incoming XML or PDF e-invoice from its content (bytes), never from a path.
readFile()  : ReadResult
Reads an incoming XML or PDF e-invoice from a file.
registerCountry()  : self
Registers a country pack with its profiles and translations and, for packs that provide them (ProvidesFormats), its formats, format aliases and serializers; a pack with the same code replaces the earlier one. Changes this instance.
render()  : RenderedInvoice
The render run behind PendingInvoice::render(): calculates the data, applies the configured defaults, chooses formats and profiles, validates, writes the XML, renders the template and the PDF/A with the embedded XML. Returns the result of the first format; the others are reachable with as().
renderDocument()  : RenderedDocument
The render run behind PendingDocument::render(): calculates the document and renders the template and, unless the format "html" is requested, the PDF. Documents carry no XML and are not validated.
resetState()  : void
Resets the process-wide state: the translator of Translations, the default snapshot upcasters of SnapshotUpcasterChain::default() and documentDefault(), the application default VAT of InvoiceBuilder::useDefaultVat() and the state that extensions registered with onResetState() (e.g. the base rates of quittio/country-de).
ruleCodes()  : array<int, string>
Codes of every PHP rule and finding with the registered profiles and country packs.
setFormatResolver()  : self
Chooses formats and profiles with $resolver from now on. Changes this instance.
setPaymentQrGenerator()  : self
Payment QR code generator for the type "auto" (before the country pack's) and the type "swiss-qr-bill", for which Quittio ships no generator; null removes it. Changes this instance.
setPostProcessor()  : self
Adds PDF/A and the embedded XML to the PDFs of renderers that cannot do it themselves (PdfRenderer::supportsEmbedding()); null = MpdfPostProcessor with the configured temp_dir.
setRenderer()  : self
Renders PDFs with $renderer from now on. Changes this instance.
setTemplateEngine()  : self
Renders the templates with $templates from now on. Changes this instance.
validateFile()  : ValidationResult
Reads and validates an incoming XML or PDF e-invoice (content, never a path) with all configured levels.
validatePath()  : ValidationResult
Reads and validates an incoming XML or PDF e-invoice from a file with all configured levels.
validators()  : array<int, ValidationDriver>
withFormatResolver()  : self
withoutValidators()  : self
withPaymentQrGenerator()  : self
withRenderer()  : self
withSerializer()  : self
withTemplateEngine()  : self
withValidator()  : self

Constants

DEFAULT_PROFILE

Profile when neither the call, the configuration nor the format names one.

public string DEFAULT_PROFILE = 'en16931'

Methods

__construct()

public __construct([Config $config = new Config() ][, ProfileRegistry $profiles = new ProfileRegistry() ][, CountryRegistry $countries = new CountryRegistry() ][, FormatRegistry $formats = new FormatRegistry() ][, PdfRenderer $renderer = new MpdfRenderer() ][, TemplateEngine $templates = new PhpTemplateEngine() ][, TotalsCalculator $calculator = new En16931Calculator() ][, Formatter $formatter = new IntlFormatter() ][, LoggerInterface|null $logger = null ][, FormatResolver|null $formatResolver = null ][, CountryResolver|null $countryResolver = null ]) : mixed
Parameters
$config : Config = new Config()
$profiles : ProfileRegistry = new ProfileRegistry()
$countries : CountryRegistry = new CountryRegistry()
$formats : FormatRegistry = new FormatRegistry()
$renderer : PdfRenderer = new MpdfRenderer()
$templates : TemplateEngine = new PhpTemplateEngine()
$calculator : TotalsCalculator = new En16931Calculator()
$formatter : Formatter = new IntlFormatter()
$logger : LoggerInterface|null = null
$formatResolver : FormatResolver|null = null
$countryResolver : CountryResolver|null = null

addSerializer()

Writes the XML of the serializer's syntax with $serializer from now on (replaces the serializer of that syntax). Changes this instance.

public addSerializer(XmlSerializer $serializer) : self
Parameters
$serializer : XmlSerializer
Return values
self

addValidator()

Runs $driver in every validation after the drivers added before. Changes this instance.

public addValidator(ValidationDriver $driver) : self
Parameters
$driver : ValidationDriver
Return values
self

cancellation()

Builder for the cancellation of an issued invoice. The sign strategy comes from the argument, the configuration or the country pack (in this order).

public cancellation(InvoiceData $original, string $number[, string|null $reason = null ][, string|null $strategy = null ][, Date|null $issueDate = null ][, array<int, BigDecimal|int|string, amount?: string}>|null $lines = null ][, CancellationHistory|null $history = null ][, string|null $title = null ]) : InvoiceBuilder
Parameters
$original : InvoiceData
$number : string
$reason : string|null = null
$strategy : string|null = null
$issueDate : Date|null = null
$lines : array<int, BigDecimal|int|string, amount?: string}>|null = null

partial cancellation; null = full

$history : CancellationHistory|null = null

earlier partial cancellations of the original, so that the VAT of a partial cancellation is rounded cumulatively with theirs (see CancellationHistory)

$title : string|null = null

document title in the PDF, e.g. "Stornorechnung"; null = the title of the country pack's correction policy ("cancellation", or "cancellation_self_billed" for self-billed originals)

Return values
InvoiceBuilder

check()

Validates like a render run, without template and PDF; see prepare().

public check(InvoiceData $data[, RenderOptions $options = new RenderOptions() ]) : ValidationResult

An explicit validation request: it validates whatever the validation mode of the configuration or the call (also "off" and withoutValidation()) and returns the result without throwing a ValidationException.

Parameters
$data : InvoiceData
$options : RenderOptions = new RenderOptions()
Tags
throws
ConfigurationException

for an unknown format or a profile the format does not support

CalculationException

when the data cannot be calculated

Return values
ValidationResult

clearValidators()

Removes every validation driver, e.g. before adding a custom set. Changes this instance.

public clearValidators() : self
Return values
self

configureRules()

Switches PHP rules off, changes the severity of their findings or replaces them, by rule code (see RuleOverrides); replaces the overrides of every PHP rules driver. Changes this instance.

public configureRules(RuleOverrides $overrides) : self
Parameters
$overrides : RuleOverrides
Tags
throws
ConfigurationException

for a code or pattern that no known rule has

Return values
self

create()

Instance with default registries, the configured validators and the given country packs.

public static create([Config|array<string, mixed> $config = [] ][, iterable<string|int, CountryPack> $countryPacks = [] ][, PdfRenderer|null $renderer = null ][, TemplateEngine|null $templates = null ][, LoggerInterface|null $logger = null ][, FormatResolver|null $formatResolver = null ][, TotalsCalculator|null $calculator = null ]) : self

Without $calculator the En16931Calculator with the calculation policy of the configuration calculates.

Parameters
$config : Config|array<string, mixed> = []
$countryPacks : iterable<string|int, CountryPack> = []
$renderer : PdfRenderer|null = null
$templates : TemplateEngine|null = null
$logger : LoggerInterface|null = null
$formatResolver : FormatResolver|null = null
$calculator : TotalsCalculator|null = null
Return values
self

edit()

Builder that continues existing invoice data, e.g. to correct a draft or an invoice read from XML: like InvoiceBuilder::from(), but the declared amounts are compared with the calculator of this instance.

public edit(InvoiceData $data) : InvoiceBuilder
Parameters
$data : InvoiceData
Return values
InvoiceBuilder

onMandatoryFieldsMissing()

Called when a template omits mandatory values, in every guard mode except "off".

public onMandatoryFieldsMissing(callable(InvoiceData, array<int, MandatoryField>): void $listener) : self
Parameters
$listener : callable(InvoiceData, array<int, MandatoryField>): void
Return values
self

onResetState()

Registers process-wide state of an extension with resetState(). A second registration under the same key replaces the first.

public static onResetState(string $key, callable(): void $reset) : void
Parameters
$key : string
$reset : callable(): void

prepare()

Calculates and validates like a render run (without template and PDF) and returns the calculated data with the chosen formats, profiles, country packs and locale.

public prepare(InvoiceData $data[, RenderOptions $options = new RenderOptions() ]) : PreparedInvoice

The run takes the same decisions as render(): format and profile, the refusal of XML formats for watermarked data, and the XML of every format that writes one, including the CII XML that "pdf" embeds with b2cEmbedXml (unless the run has a watermark). The data and xml stages (L1–L5, L7) run with all configured drivers; L6 needs the rendered PDF and does not run. The Managed layer freezes invoices with it, so it always validates, whatever the validation mode (also "off" and withoutValidation()), and never throws a ValidationException: the caller decides on the result. Configuration errors (e.g. an unsupported profile) still throw.

Parameters
$data : InvoiceData
$options : RenderOptions = new RenderOptions()
Tags
throws
ConfigurationException

for an unknown format or a profile the format does not support

CalculationException

when the data cannot be calculated

Return values
PreparedInvoice

read()

Reads an incoming XML or PDF e-invoice from its content (bytes), never from a path.

public read(string $content) : ReadResult
Parameters
$content : string
Tags
throws
UnsafeXmlException

when the XML is too large, not well-formed or not allowed (DOCTYPE, limits)

PdfException

when the PDF is too large, encrypted, malformed or exceeds a limit

UnreadableInvoiceException

for an unknown format, ZUGFeRD 1.0 or a PDF without an embedded invoice

Return values
ReadResult

readFile()

Reads an incoming XML or PDF e-invoice from a file.

public readFile(string $path) : ReadResult
Parameters
$path : string
Tags
throws
UnsafeXmlException

when the XML is too large, not well-formed or not allowed (DOCTYPE, limits)

PdfException

when the PDF is too large, encrypted, malformed or exceeds a limit

UnreadableInvoiceException

for an unknown format, ZUGFeRD 1.0, a PDF without an embedded invoice, or a file that cannot be read

Return values
ReadResult

registerCountry()

Registers a country pack with its profiles and translations and, for packs that provide them (ProvidesFormats), its formats, format aliases and serializers; a pack with the same code replaces the earlier one. Changes this instance.

public registerCountry(CountryPack $pack) : self
Parameters
$pack : CountryPack
Return values
self

render()

The render run behind PendingInvoice::render(): calculates the data, applies the configured defaults, chooses formats and profiles, validates, writes the XML, renders the template and the PDF/A with the embedded XML. Returns the result of the first format; the others are reachable with as().

public render(InvoiceData $data[, RenderOptions $options = new RenderOptions() ]) : RenderedInvoice
Parameters
$data : InvoiceData
$options : RenderOptions = new RenderOptions()
Tags
throws
ValidationException

when validation finds errors in the mode "error"

ConfigurationException

for an unknown format, a profile the format does not support or a watermark with e-invoice XML

MandatoryFieldMissing

when the template omits mandatory values in the guard mode "exception"

CalculationException

when the data cannot be calculated

InvalidInvoiceData

when a text cannot be written to XML (control characters, invalid UTF-8)

PdfException

when the PDF cannot be rendered or post-processed

Return values
RenderedInvoice

renderDocument()

The render run behind PendingDocument::render(): calculates the document and renders the template and, unless the format "html" is requested, the PDF. Documents carry no XML and are not validated.

public renderDocument(DocumentData $document[, RenderOptions $options = new RenderOptions() ]) : RenderedDocument
Parameters
$document : DocumentData
$options : RenderOptions = new RenderOptions()
Tags
throws
CalculationException

when the document cannot be calculated

PdfException

when the PDF cannot be rendered

Return values
RenderedDocument

resetState()

Resets the process-wide state: the translator of Translations, the default snapshot upcasters of SnapshotUpcasterChain::default() and documentDefault(), the application default VAT of InvoiceBuilder::useDefaultVat() and the state that extensions registered with onResetState() (e.g. the base rates of quittio/country-de).

public static resetState() : void

Test suites call it between tests, long-running processes between tenants. The Laravel integration sets the state again when the application boots.

ruleCodes()

Codes of every PHP rule and finding with the registered profiles and country packs.

public ruleCodes() : array<int, string>
Return values
array<int, string>

setFormatResolver()

Chooses formats and profiles with $resolver from now on. Changes this instance.

public setFormatResolver(FormatResolver $resolver) : self
Parameters
$resolver : FormatResolver
Return values
self

setPaymentQrGenerator()

Payment QR code generator for the type "auto" (before the country pack's) and the type "swiss-qr-bill", for which Quittio ships no generator; null removes it. Changes this instance.

public setPaymentQrGenerator(PaymentQrGenerator|null $generator) : self
Parameters
$generator : PaymentQrGenerator|null
Return values
self

setPostProcessor()

Adds PDF/A and the embedded XML to the PDFs of renderers that cannot do it themselves (PdfRenderer::supportsEmbedding()); null = MpdfPostProcessor with the configured temp_dir.

public setPostProcessor(PdfPostProcessor|null $postProcessor) : self

Changes this instance.

Parameters
$postProcessor : PdfPostProcessor|null
Return values
self

setRenderer()

Renders PDFs with $renderer from now on. Changes this instance.

public setRenderer(PdfRenderer $renderer) : self
Parameters
$renderer : PdfRenderer
Return values
self

setTemplateEngine()

Renders the templates with $templates from now on. Changes this instance.

public setTemplateEngine(TemplateEngine $templates) : self
Parameters
$templates : TemplateEngine
Return values
self

validateFile()

Reads and validates an incoming XML or PDF e-invoice (content, never a path) with all configured levels.

public validateFile(string $content) : ValidationResult
Parameters
$content : string
Tags
throws
UnsafeXmlException

when the XML is too large, not well-formed or not allowed (DOCTYPE, limits)

PdfException

when the PDF is too large, encrypted, malformed or exceeds a limit

UnreadableInvoiceException

for an unknown format, ZUGFeRD 1.0 or a PDF without an embedded invoice

Return values
ValidationResult

validatePath()

Reads and validates an incoming XML or PDF e-invoice from a file with all configured levels.

public validatePath(string $path) : ValidationResult
Parameters
$path : string
Tags
throws
UnsafeXmlException

when the XML is too large, not well-formed or not allowed (DOCTYPE, limits)

PdfException

when the PDF is too large, encrypted, malformed or exceeds a limit

UnreadableInvoiceException

for an unknown format, ZUGFeRD 1.0, a PDF without an embedded invoice, or a file that cannot be read

Return values
ValidationResult

withFormatResolver()

public withFormatResolver(FormatResolver $resolver) : self

use setFormatResolver(); like it, it changes this instance

Parameters
$resolver : FormatResolver
Return values
self

withoutValidators()

public withoutValidators() : self

use clearValidators(); like it, it changes this instance

Return values
self

withPaymentQrGenerator()

public withPaymentQrGenerator(PaymentQrGenerator|null $generator) : self

use setPaymentQrGenerator(); like it, it changes this instance

Parameters
$generator : PaymentQrGenerator|null
Return values
self

withRenderer()

public withRenderer(PdfRenderer $renderer) : self

use setRenderer(); like it, it changes this instance

Parameters
$renderer : PdfRenderer
Return values
self

withSerializer()

public withSerializer(XmlSerializer $serializer) : self

use addSerializer(); like it, it changes this instance

Parameters
$serializer : XmlSerializer
Return values
self

withTemplateEngine()

public withTemplateEngine(TemplateEngine $templates) : self

use setTemplateEngine(); like it, it changes this instance

Parameters
$templates : TemplateEngine
Return values
self
On this page

Search results