Skip to content

API reference / Quittio \ Core \ Documents

DocumentBuilder

class in quittio/core · uses Macroable

Quittio\Core\Documents\DocumentBuilder · Source

Fluent builder for documents. Parties, lines, notes, discounts and payment data work exactly like in the {@see InvoiceBuilder}.

Properties#

PropertyTypeDescription
$macros protected staticarray<string, callable>

Methods#

MethodDescription
->__construct()
->__call()
::accountStatement()An account statement (Kontoauszug): open items of a statementPeriod() with an opening balance.
->alternativeLine()Alternative to another line, shown but not included in the totals.
->bonus()The reduction of the net amount of one VAT rate of a bonus statement, as a line; the VAT of the reduction follows from the rate. For exempt supplies pass their category and exemption reason.
->bonusAgreement()The agreement a bonus statement is based on, e.g. "der Bonusvereinbarung vom 15.01.2026"; the statement names it.
->bonusInvoices()Numbers of the invoices a bonus statement concerns (optional, listed on the statement).
->bonusOnRevenue()The reduction of one VAT rate as a percentage of the revenue of that rate in the period, e.g. 3 % of 100,000.00: a line of 3,000.00 with the revenue and the percentage as description.
->bonusPeriod()Period of the supplies a bonus statement reduces, e.g. a calendar year.
::bonusStatement()A bonus statement (Bonusabrechnung): the reduction of the consideration of the supplies of a bonusPeriod() under a bonusAgreement(), per VAT rate with bonus() or bonusOnRevenue() (in Germany section 17 (4) UStG).
->build()The immutable document, not calculated yet (DocumentCalculator, or the render run).
->buyer()
->buyerReference()The buyer's reference; null removes it.
->cashDiscount()Cash discount ("Skonto"), see InvoiceBuilder::cashDiscount().
->creditTransfer()Bank account for the payment, see InvoiceBuilder::creditTransfer().
->currency()Currency, ISO 4217; default EUR.
->custom()Free data for templates (view model key meta.custom).
->deadline()Payment deadline of a payment reminder.
->defaultVat()VAT treatment of the lines that set none, see InvoiceBuilder::defaultVat().
->deliverTo()Deliver-to party: recipient name and address, see InvoiceBuilder::deliverTo().
->deliveryDate()Delivery date.
::deliveryNote()A delivery note (Lieferschein), e.g. with packages and serialised lines.
->discountAmount()Absolute discount on the lines that count towards the totals, see InvoiceBuilder::discountAmount().
->discountPercent()Percentage discount on the lines that count towards the totals, see InvoiceBuilder::discountPercent().
->dueInDays()Payment target in days, see InvoiceBuilder::dueInDays().
->fee()Adds a fee of a payment reminder, e.g. a reminder fee.
->flatRate()Adds the flat rate for recovery costs of a late payment (Article 6 Directive 2011/7/EU; section 288 (5) BGB: 40 EUR) for one claim, e.g. an invoice or an instalment. It is owed once per late payment, only by businesses, and counts towards other recovery costs such as reminder fees, which may then be claimed only in so far as they exceed it.
::flushMacros()
::hasMacro()
->interest()Default interest from $from (first day with interest) until $until (exclusive: the last day with interest is the day before). $dayCount null counts actual/actual (365 or 366 days per calendar year); 365 or 360 use a fixed basis, e.g. from the dayCount of the country pack's DunningLaw.
->interestCharge()Adds calculated interest charges, e.g. of Dunning\DefaultInterest::calculate(), with their own day count basis and texts. The base is taken over as amount in the document currency.
->issueDate()Document date; default today.
->line()A line in the forms of InvoiceBuilder::line(), e.g. ->line('Consulting', netPrice: '120.00').
->lines()
->locale()Language of the document, see InvoiceBuilder::locale().
::macro()
::make()A new builder for a document of $type.
->note()Adds a note with an optional subject code, see InvoiceBuilder::note().
->number()Document number.
->openingBalance()Opening balance of an account statement.
->openItem()Adds an open invoice of a payment reminder or account statement: number, date, amount (string), due date, the amount paid so far and a description.
->optionalLine()Optional quote line, shown with its price but not included in the totals.
::orderConfirmation()An order confirmation (Auftragsbestätigung), e.g. with reference() to the quote.
->package()Adds a package of a delivery note.
::paymentReminder()
->paymentTerms()
->presentation()Design of this document, see InvoiceBuilder::presentation().
::proforma()A proforma invoice: looks like an invoice, but is not one for tax purposes.
->purchaseOrderReference()The buyer's purchase order reference; null removes it.
::quote()A quote (Angebot): lines, optional and alternative lines, validUntil().
->reference()Preceding document, e.g. the quote of an order confirmation or the order of a delivery note.
->seller()
->serialisedLine()Delivery note line with serial numbers.
->statementPeriod()Period of an account statement.
->tap()Direct access to the underlying invoice builder for everything not wrapped here.
->validUntil()Date until which a quote is valid.

__construct()#

final public function __construct(DocumentType $type)
ParameterTypeDescription
$typeDocumentType

__call()#

public function __call(string $method, array<mixed> $parameters): mixed
ParameterTypeDescription
$methodstring
$parametersarray<mixed>
Returns
mixed

accountStatement()#

public static function accountStatement(): static

static

An account statement (Kontoauszug): open items of a statementPeriod() with an opening balance.

Returns
static

alternativeLine()#

public function alternativeLine(
    string $alternativeTo,
    InvoiceLine|LineBuilder|array|callable|string $line,
    BigDecimal|int|float|string|null $netPrice = null,
    BigDecimal|int|float|string|null $quantity = null,
    UnitCode|RawCode|string|null $unit = null,
    TaxPreset|VatCategory|null $vat = null,
    ?string $description = null,
    BigDecimal|int|float|string|null $priceInclVat = null,
): static

Alternative to another line, shown but not included in the totals.

ParameterTypeDescription
$alternativeTostring
$lineInvoiceLine|LineBuilder|array|callable|string
$netPriceBrick\Math\BigDecimal|int|float|string|null = null
$quantityBrick\Math\BigDecimal|int|float|string|null = null
$unitUnitCode|RawCode|string|null = null
$vatTaxPreset|VatCategory|null = null
$description?string = null
$priceInclVatBrick\Math\BigDecimal|int|float|string|null = null
Returns
static

bonus()#

public function bonus(
    BigDecimal|int|string $net,
    TaxPreset|VatCategory $vat,
    BigDecimal|int|string|null $rate = null,
    ?string $exemptionReason = null,
    VatExemptionReasonCode|RawCode|string|null $exemptionReasonCode = null,
    ?string $description = null,
): static

The reduction of the net amount of one VAT rate of a bonus statement, as a line; the VAT of the reduction follows from the rate. For exempt supplies pass their category and exemption reason.

ParameterTypeDescription
$netBrick\Math\BigDecimal|int|string
$vatTaxPreset|VatCategory
$rateBrick\Math\BigDecimal|int|string|null = null
$exemptionReason?string = null
$exemptionReasonCodeVatExemptionReasonCode|RawCode|string|null = null
$description?string = null
Returns
static

bonusAgreement()#

public function bonusAgreement(string $agreement): static

The agreement a bonus statement is based on, e.g. "der Bonusvereinbarung vom 15.01.2026"; the statement names it.

ParameterTypeDescription
$agreementstring
Returns
static

bonusInvoices()#

public function bonusInvoices(string ...$numbers): static

Numbers of the invoices a bonus statement concerns (optional, listed on the statement).

ParameterTypeDescription
...$numbersstring
Returns
static

bonusOnRevenue()#

public function bonusOnRevenue(
    BigDecimal|int|string $revenue,
    BigDecimal|int|string $percent,
    TaxPreset|VatCategory $vat,
    BigDecimal|int|string|null $rate = null,
    ?string $exemptionReason = null,
    VatExemptionReasonCode|RawCode|string|null $exemptionReasonCode = null,
): static

The reduction of one VAT rate as a percentage of the revenue of that rate in the period, e.g. 3 % of 100,000.00: a line of 3,000.00 with the revenue and the percentage as description.

ParameterTypeDescription
$revenueBrick\Math\BigDecimal|int|string
$percentBrick\Math\BigDecimal|int|string
$vatTaxPreset|VatCategory
$rateBrick\Math\BigDecimal|int|string|null = null
$exemptionReason?string = null
$exemptionReasonCodeVatExemptionReasonCode|RawCode|string|null = null
Returns
static

bonusPeriod()#

public function bonusPeriod(
    Date|DateTimeInterface|string $start,
    Date|DateTimeInterface|string $end,
): static

Period of the supplies a bonus statement reduces, e.g. a calendar year.

ParameterTypeDescription
$startDate|DateTimeInterface|string
$endDate|DateTimeInterface|string
Returns
static

bonusStatement()#

public static function bonusStatement(): static

static

A bonus statement (Bonusabrechnung): the reduction of the consideration of the supplies of a bonusPeriod() under a bonusAgreement(), per VAT rate with bonus() or bonusOnRevenue() (in Germany section 17 (4) UStG).

Returns
static

build()#

public function build(): DocumentData

The immutable document, not calculated yet (DocumentCalculator, or the render run).

Returns
DocumentData
Throws
InvalidInvoiceData – when the seller or the buyer is missing, or an item name or the VAT of a line without default VAT

buyer()#

public function buyer(BuyerParty|PartyBuilder|ProvidesParty|callable $buyer): static
ParameterTypeDescription
$buyerBuyerParty|PartyBuilder|ProvidesParty|callable
Returns
static

buyerReference()#

public function buyerReference(?string $reference): static

The buyer's reference; null removes it.

ParameterTypeDescription
$reference?string
Returns
static

cashDiscount()#

public function cashDiscount(
    int $days,
    string $percent,
    ?string $baseAmount = null,
): static

Cash discount ("Skonto"), see InvoiceBuilder::cashDiscount().

ParameterTypeDescription
$daysint
$percentstring
$baseAmount?string = null
Returns
static

creditTransfer()#

public function creditTransfer(
    string $iban,
    ?string $bic = null,
    ?string $accountName = null,
): static

Bank account for the payment, see InvoiceBuilder::creditTransfer().

ParameterTypeDescription
$ibanstring
$bic?string = null
$accountName?string = null
Returns
static

currency()#

public function currency(string $currency): static

Currency, ISO 4217; default EUR.

ParameterTypeDescription
$currencystring
Returns
static

custom()#

public function custom(string $key, mixed $value): static

Free data for templates (view model key meta.custom).

ParameterTypeDescription
$keystring
$valuemixed
Returns
static

deadline()#

public function deadline(Date|DateTimeInterface|string $date): static

Payment deadline of a payment reminder.

ParameterTypeDescription
$dateDate|DateTimeInterface|string
Returns
static

defaultVat()#

public function defaultVat(
    TaxPreset|VatCategory $presetOrCategory,
    BigDecimal|int|float|string|null $rate = null,
    ?string $exemptionReason = null,
    VatExemptionReasonCode|RawCode|string|null $exemptionReasonCode = null,
): static

VAT treatment of the lines that set none, see InvoiceBuilder::defaultVat().

ParameterTypeDescription
$presetOrCategoryTaxPreset|VatCategory
$rateBrick\Math\BigDecimal|int|float|string|null = null
$exemptionReason?string = null
$exemptionReasonCodeVatExemptionReasonCode|RawCode|string|null = null
Returns
static

deliverTo()#

public function deliverTo(?string $recipientName, ?Address $address = null): static

Deliver-to party: recipient name and address, see InvoiceBuilder::deliverTo().

ParameterTypeDescription
$recipientName?string
$address?Address = null
Returns
static

deliveryDate()#

public function deliveryDate(Date|DateTimeInterface|string $date): static

Delivery date.

ParameterTypeDescription
$dateDate|DateTimeInterface|string
Returns
static

deliveryNote()#

public static function deliveryNote(): static

static

A delivery note (Lieferschein), e.g. with packages and serialised lines.

Returns
static

discountAmount()#

public function discountAmount(
    BigDecimal|int|float|string $amount,
    ?string $reason = null,
    AllowanceReasonCode|RawCode|string|null $reasonCode = \Quittio\Core\Enums\AllowanceReasonCode::Discount,
): static

Absolute discount on the lines that count towards the totals, see InvoiceBuilder::discountAmount().

ParameterTypeDescription
$amountBrick\Math\BigDecimal|int|float|string
$reason?string = null
$reasonCodeAllowanceReasonCode|RawCode|string|null = \Quittio\Core\Enums\AllowanceReasonCode::Discount
Returns
static

discountPercent()#

public function discountPercent(
    BigDecimal|int|float|string $percent,
    ?string $reason = null,
    AllowanceReasonCode|RawCode|string|null $reasonCode = \Quittio\Core\Enums\AllowanceReasonCode::Discount,
): static

Percentage discount on the lines that count towards the totals, see InvoiceBuilder::discountPercent().

ParameterTypeDescription
$percentBrick\Math\BigDecimal|int|float|string
$reason?string = null
$reasonCodeAllowanceReasonCode|RawCode|string|null = \Quittio\Core\Enums\AllowanceReasonCode::Discount
Returns
static

dueInDays()#

public function dueInDays(int $days): static

Payment target in days, see InvoiceBuilder::dueInDays().

ParameterTypeDescription
$daysint
Returns
static

fee()#

public function fee(string $description, BigDecimal|int|float|string $amount): static

Adds a fee of a payment reminder, e.g. a reminder fee.

ParameterTypeDescription
$descriptionstring
$amountBrick\Math\BigDecimal|int|float|string
Returns
static
Throws
InvalidArgumentException – for a float amount

flatRate()#

public function flatRate(
    string $claim,
    BigDecimal|int|string $amount = '40.00',
    ?string $description = null,
): static

Adds the flat rate for recovery costs of a late payment (Article 6 Directive 2011/7/EU; section 288 (5) BGB: 40 EUR) for one claim, e.g. an invoice or an instalment. It is owed once per late payment, only by businesses, and counts towards other recovery costs such as reminder fees, which may then be claimed only in so far as they exceed it.

ParameterTypeDescription
$claimstring
$amountBrick\Math\BigDecimal|int|string = '40.00'
$description?string = null
Returns
static
Throws
InvalidArgumentException – for a float amount; when building, for a second flat rate of the same claim or a consumer as buyer

flushMacros()#

public static function flushMacros(): void

static

hasMacro()#

public static function hasMacro(string $name): bool

static

ParameterTypeDescription
$namestring
Returns
bool

interest()#

public function interest(
    string $base,
    BigDecimal|string $ratePercent,
    Date|DateTimeInterface|string $from,
    Date|DateTimeInterface|string $until,
    ?string $description = null,
    ?int $dayCount = \Quittio\Core\Documents\InterestCharge::ACTUAL_ACTUAL,
): static

Default interest from $from (first day with interest) until $until (exclusive: the last day with interest is the day before). $dayCount null counts actual/actual (365 or 366 days per calendar year); 365 or 360 use a fixed basis, e.g. from the dayCount of the country pack's DunningLaw.

ParameterTypeDescription
$basestring
$ratePercentBrick\Math\BigDecimal|string
$fromDate|DateTimeInterface|string
$untilDate|DateTimeInterface|string
$description?string = null
$dayCount?int = \Quittio\Core\Documents\InterestCharge::ACTUAL_ACTUAL
Returns
static

interestCharge()#

public function interestCharge(InterestCharge ...$charges): static

Adds calculated interest charges, e.g. of Dunning\DefaultInterest::calculate(), with their own day count basis and texts. The base is taken over as amount in the document currency.

ParameterTypeDescription
...$chargesInterestCharge
Returns
static

issueDate()#

public function issueDate(Date|DateTimeInterface|string $date): static

Document date; default today.

ParameterTypeDescription
$dateDate|DateTimeInterface|string
Returns
static

line()#

public function line(
    InvoiceLine|LineBuilder|ProvidesInvoiceLine|array|callable|string $line,
    BigDecimal|int|float|string|null $netPrice = null,
    BigDecimal|int|float|string|null $quantity = null,
    UnitCode|RawCode|string|null $unit = null,
    TaxPreset|VatCategory|null $vat = null,
    ?string $description = null,
    BigDecimal|int|float|string|null $priceInclVat = null,
    ?DocumentLineOptions $options = null,
): static

A line in the forms of InvoiceBuilder::line(), e.g. ->line('Consulting', netPrice: '120.00').

ParameterTypeDescription
$lineInvoiceLine|LineBuilder|ProvidesInvoiceLine|array|callable|string
$netPriceBrick\Math\BigDecimal|int|float|string|null = null
$quantityBrick\Math\BigDecimal|int|float|string|null = null
$unitUnitCode|RawCode|string|null = null
$vatTaxPreset|VatCategory|null = null
$description?string = null
$priceInclVatBrick\Math\BigDecimal|int|float|string|null = null
$options?DocumentLineOptions = null
Returns
static

lines()#

public function lines(
    iterable<InvoiceLine|LineBuilder|ProvidesInvoiceLine|array<array-key, mixed>|callable(LineBuilder): mixed|string> $lines,
): static
ParameterTypeDescription
$linesiterable<InvoiceLine|LineBuilder|ProvidesInvoiceLine|array<array-key, mixed>|callable(LineBuilder): mixed|string>
Returns
static

locale()#

public function locale(string $locale): static

Language of the document, see InvoiceBuilder::locale().

ParameterTypeDescription
$localestring
Returns
static

macro()#

public static function macro(string $name, callable $macro): void

static

ParameterTypeDescription
$namestring
$macrocallable

make()#

public static function make(DocumentType $type): static

static

A new builder for a document of $type.

ParameterTypeDescription
$typeDocumentType
Returns
static

note()#

public function note(
    string $content,
    NoteSubjectCode|RawCode|string|null $subject = null,
): static

Adds a note with an optional subject code, see InvoiceBuilder::note().

ParameterTypeDescription
$contentstring
$subjectNoteSubjectCode|RawCode|string|null = null
Returns
static

number()#

public function number(string $number): static

Document number.

ParameterTypeDescription
$numberstring
Returns
static

openingBalance()#

public function openingBalance(BigDecimal|int|float|string $amount): static

Opening balance of an account statement.

ParameterTypeDescription
$amountBrick\Math\BigDecimal|int|float|string
Returns
static
Throws
InvalidArgumentException – for a float amount

openItem()#

public function openItem(
    string $invoiceNumber,
    Date|DateTimeInterface|string $invoiceDate,
    string $amount,
    Date|DateTimeInterface|string|null $dueDate = null,
    ?string $paid = null,
    ?string $description = null,
): static

Adds an open invoice of a payment reminder or account statement: number, date, amount (string), due date, the amount paid so far and a description.

ParameterTypeDescription
$invoiceNumberstring
$invoiceDateDate|DateTimeInterface|string
$amountstring
$dueDateDate|DateTimeInterface|string|null = null
$paid?string = null
$description?string = null
Returns
static

optionalLine()#

public function optionalLine(
    InvoiceLine|LineBuilder|array|callable|string $line,
    BigDecimal|int|float|string|null $netPrice = null,
    BigDecimal|int|float|string|null $quantity = null,
    UnitCode|RawCode|string|null $unit = null,
    TaxPreset|VatCategory|null $vat = null,
    ?string $description = null,
    BigDecimal|int|float|string|null $priceInclVat = null,
): static

Optional quote line, shown with its price but not included in the totals.

ParameterTypeDescription
$lineInvoiceLine|LineBuilder|array|callable|string
$netPriceBrick\Math\BigDecimal|int|float|string|null = null
$quantityBrick\Math\BigDecimal|int|float|string|null = null
$unitUnitCode|RawCode|string|null = null
$vatTaxPreset|VatCategory|null = null
$description?string = null
$priceInclVatBrick\Math\BigDecimal|int|float|string|null = null
Returns
static

orderConfirmation()#

public static function orderConfirmation(): static

static

An order confirmation (Auftragsbestätigung), e.g. with reference() to the quote.

Returns
static

package()#

public function package(Package $package): static

Adds a package of a delivery note.

ParameterTypeDescription
$packagePackage
Returns
static

paymentReminder()#

public static function paymentReminder(int $level = 0): static

static

ParameterTypeDescription
$levelint = 00 = payment reminder (Zahlungserinnerung), 1 = first formal reminder (1. Mahnung), 2 = second …
Returns
static

paymentTerms()#

public function paymentTerms(PaymentTerms|string|callable $terms): static
ParameterTypeDescription
$termsPaymentTerms|string|callable
Returns
static

presentation()#

public function presentation(Presentation|array|callable $presentation): static

Design of this document, see InvoiceBuilder::presentation().

ParameterTypeDescription
$presentationPresentation|array|callable
Returns
static

proforma()#

public static function proforma(): static

static

A proforma invoice: looks like an invoice, but is not one for tax purposes.

Returns
static

purchaseOrderReference()#

public function purchaseOrderReference(?string $reference): static

The buyer's purchase order reference; null removes it.

ParameterTypeDescription
$reference?string
Returns
static

quote()#

public static function quote(): static

static

A quote (Angebot): lines, optional and alternative lines, validUntil().

Returns
static

reference()#

public function reference(
    string $number,
    Date|DateTimeInterface|string|null $date = null,
): static

Preceding document, e.g. the quote of an order confirmation or the order of a delivery note.

ParameterTypeDescription
$numberstring
$dateDate|DateTimeInterface|string|null = null
Returns
static

seller()#

public function seller(SellerParty|PartyBuilder|ProvidesParty|callable $seller): static
ParameterTypeDescription
$sellerSellerParty|PartyBuilder|ProvidesParty|callable
Returns
static

serialisedLine()#

public function serialisedLine(
    InvoiceLine|LineBuilder|array|callable|string $line,
    list<string> $serialNumbers,
    BigDecimal|int|float|string|null $netPrice = null,
    BigDecimal|int|float|string|null $quantity = null,
    UnitCode|RawCode|string|null $unit = null,
    TaxPreset|VatCategory|null $vat = null,
    ?string $description = null,
    BigDecimal|int|float|string|null $priceInclVat = null,
): static

Delivery note line with serial numbers.

ParameterTypeDescription
$lineInvoiceLine|LineBuilder|array|callable|string
$serialNumberslist<string>
$netPriceBrick\Math\BigDecimal|int|float|string|null = null
$quantityBrick\Math\BigDecimal|int|float|string|null = null
$unitUnitCode|RawCode|string|null = null
$vatTaxPreset|VatCategory|null = null
$description?string = null
$priceInclVatBrick\Math\BigDecimal|int|float|string|null = null
Returns
static

statementPeriod()#

public function statementPeriod(
    Date|DateTimeInterface|string $start,
    Date|DateTimeInterface|string $end,
): static

Period of an account statement.

ParameterTypeDescription
$startDate|DateTimeInterface|string
$endDate|DateTimeInterface|string
Returns
static

tap()#

public function tap(callable $callback): static

Direct access to the underlying invoice builder for everything not wrapped here.

ParameterTypeDescription
$callbackcallable
Returns
static

validUntil()#

public function validUntil(Date|DateTimeInterface|string $date): static

Date until which a quote is valid.

ParameterTypeDescription
$dateDate|DateTimeInterface|string
Returns
static

The open core packages are MIT licensed. The legal wording of the country packs must be confirmed by a tax adviser.