API reference / Quittio \ Core \ Builder

LineBuilder

final class in quittio/core · uses Macroable

Quittio\Core\Builder\LineBuilder · Source

Fluent builder for an invoice line (BG-25).

Constants#

Constant	Value	Description
`ARRAY_KEYS`	`['id', 'name', 'description', 'note', 'quantity', 'unit', 'netPrice', 'listPrice', 'priceInclVat', 'vat', 'period', 'allowance', 'charge', 'sellerId', 'buyerId' …`	Keys of a line given as array (InvoiceBuilder::line(), Line::fromArray()): the methods of this builder that can be called with the value.

Properties#

Property	Type	Description
`$macros` protected static	`array<string, callable>`

Methods#

Method	Description
`->__call()`
`->allowance()`	Adds a line allowance (BG-27): an amount (BT-136), or a percentage (BT-138) of the base amount (BT-137, default quantity × net price), with reason (BT-139) and reason code (BT-140).
`->attribute()`	Adds an item attribute (BG-32): name (BT-160) and value (BT-161).
`->build()`	Builds the line; called by InvoiceBuilder. $vatDefault is a builder whose VAT treatment applies to this line and its sub lines when they have none (InvoiceBuilder::defaultVat()). $supplyDate is the supply date of the document (SupplyDate); a line period wins. It resolves presets whose rate depends on the date (DatedTaxPreset).
`->buyerAccountingReference()`	The buyer's accounting reference of the line (BT-133); null removes it.
`->buyerId()`	The buyer's item number (BT-156); null removes it.
`->charge()`	Adds a line charge (BG-28): an amount (BT-141), or a percentage (BT-143) of the base amount (BT-142, default quantity × net price), with reason (BT-144) and reason code (BT-145).
`->classification()`	Adds an item classification (BT-158) with list identifier (BT-158-1) and version (BT-158-2).
`->description()`	Item description (BT-154); null removes it.
`->explicitId()`	Identifier set with id(); null when the invoice builder assigns one.
`->extended()`	Line data of the profile EXTENDED; other profiles do not write it.
`->fill()`	Calls the method of every key with its value: ['name' => 'Consulting', 'quantity' => 4, 'netPrice' => '120.00']. An array value holds the arguments, as list or by name (['quantity' => [4, UnitCode::Hour]], ['allowance' => ['percent' => '10', 'reason' => 'Early bird']]); null values are skipped.
`::flushMacros()`
`->fromModel()`	Lets an application model fill this line (ProvidesInvoiceLine::fillLine()).
`->group()`	Assigns the line to a presentation group of the PDF (see InvoiceBuilder::group()).
`::hasMacro()`
`->hasPrice()`	Whether a net price, list price or price including VAT was set.
`->hasVat()`	Whether vat() was called.
`->highlight()`	Highlights the line in the PDF and HTML (the default templates shade it and mark it in the secondary colour).
`->id()`	Line identifier (BT-126); default the position, "1", "2", …
`->lacksVat()`	Whether the line or one of its sub lines has no VAT treatment yet.
`->listPrice()`	List price before price discount (BT-148) and the discount per unit (BT-147). The net price is derived as list price minus discount unless set explicitly.
`::macro()`
`->name()`	Item name (BT-153). Required.
`->netPrice()`	Net price per base quantity (BT-146, BT-149, BT-150).
`->note()`	Line note (BT-127); null removes it.
`->objectId()`	Invoiced object identifier of the line (BT-128) with its scheme.
`->orderLineReference()`	Line of the purchase order (BT-132); null removes it.
`->originCountry()`	Country of origin of the item (BT-159), ISO 3166-1 alpha-2, uppercased; null removes it.
`->period()`	Line period (BG-26): start (BT-134) and end (BT-135); one of them may be null.
`->priceInclVat()`	Price including VAT (gross price mode for B2C and shops). The calculator derives the net price so that the customer pays exactly the gross amount.
`->quantity()`	Invoiced quantity (BT-129), optionally with the unit (BT-130); default 1. Negative quantities for returns and discounts.
`->reference()`	Adds a reference to an order, contract, despatch or receiving advice or another document (profile EXTENDED only).
`->sellerId()`	The seller's item number (BT-155); null removes it.
`->showGrossPrice()`	Prints the price including VAT below the net unit price of this line (true) or not (false), whatever Presentation::$showGrossPrices says for the invoice; null follows the presentation again. It is printed only for lines with a price including VAT (priceInclVat()).
`->standardId()`	Standard item identifier (BT-157) with its scheme (BT-157-1); default scheme GTIN (0160).
`->subLine()`	Adds a sub line (profile EXTENDED or XRechnung extension), in the forms of InvoiceBuilder::line(): a name with the common values, Line::make(), an array, a model or a callable.
`->unit()`	Unit of the quantity (BT-130), UN/ECE Recommendation 20/21; default C62 (one). Unknown codes are kept as RawCode.
`->vat()`	Sets the VAT treatment, either via a preset of a country pack or as category and rate.

`__call()`#

public function __call(string $method, array<mixed> $parameters): mixed

Parameter	Type	Description
`$method`	`string`
`$parameters`	`array<mixed>`

Returns: mixed

`allowance()`#

public function allowance(
    ?string $amount = null,
    ?string $percent = null,
    ?string $reason = null,
    AllowanceReasonCode|RawCode|string|null $reasonCode = null,
    ?string $baseAmount = null,
): self

Adds a line allowance (BG-27): an amount (BT-136), or a percentage (BT-138) of the base amount (BT-137, default quantity × net price), with reason (BT-139) and reason code (BT-140).

Parameter	Type	Description
`$amount`	`?string` = `null`
`$percent`	`?string` = `null`
`$reason`	`?string` = `null`
`$reasonCode`	`AllowanceReasonCode\|RawCode\|string\|null` = `null`
`$baseAmount`	`?string` = `null`

Returns: self

`attribute()`#

public function attribute(string $name, string $value): self

Adds an item attribute (BG-32): name (BT-160) and value (BT-161).

Parameter	Type	Description
`$name`	`string`
`$value`	`string`

Returns: self

`build()`#

public function build(
    string $currency,
    string $defaultId,
    ?string $locale = null,
    ?self $vatDefault = null,
    ?Date $supplyDate = null,
): InvoiceLine

Builds the line; called by InvoiceBuilder. $vatDefault is a builder whose VAT treatment applies to this line and its sub lines when they have none (InvoiceBuilder::defaultVat()). $supplyDate is the supply date of the document (SupplyDate); a line period wins. It resolves presets whose rate depends on the date (DatedTaxPreset).

Parameter	Type	Description
`$currency`	`string`
`$defaultId`	`string`
`$locale`	`?string` = `null`
`$vatDefault`	`?self` = `null`
`$supplyDate`	`?Date` = `null`

Returns: InvoiceLine

`buyerAccountingReference()`#

public function buyerAccountingReference(?string $reference): self

The buyer's accounting reference of the line (BT-133); null removes it.

Parameter	Type	Description
`$reference`	`?string`

Returns: self

`buyerId()`#

public function buyerId(?string $id): self

The buyer's item number (BT-156); null removes it.

Parameter	Type	Description
`$id`	`?string`

Returns: self

`charge()`#

public function charge(
    ?string $amount = null,
    ?string $percent = null,
    ?string $reason = null,
    ChargeReasonCode|RawCode|string|null $reasonCode = null,
    ?string $baseAmount = null,
): self

Adds a line charge (BG-28): an amount (BT-141), or a percentage (BT-143) of the base amount (BT-142, default quantity × net price), with reason (BT-144) and reason code (BT-145).

Parameter	Type	Description
`$amount`	`?string` = `null`
`$percent`	`?string` = `null`
`$reason`	`?string` = `null`
`$reasonCode`	`ChargeReasonCode\|RawCode\|string\|null` = `null`
`$baseAmount`	`?string` = `null`

Returns: self

`classification()`#

public function classification(
    string $code,
    ItemClassificationScheme|RawCode|string $scheme,
    ?string $version = null,
): self

Adds an item classification (BT-158) with list identifier (BT-158-1) and version (BT-158-2).

Parameter	Type	Description
`$code`	`string`
`$scheme`	`ItemClassificationScheme\|RawCode\|string`
`$version`	`?string` = `null`

Returns: self

`description()`#

public function description(?string $description): self

Item description (BT-154); null removes it.

Parameter	Type	Description
`$description`	`?string`

Returns: self

`explicitId()`#

public function explicitId(): ?string

Identifier set with id(); null when the invoice builder assigns one.

Returns: ?string

`extended()`#

public function extended(LineExtendedData $extended): self

Line data of the profile EXTENDED; other profiles do not write it.

Parameter	Type	Description
`$extended`	`LineExtendedData`

Returns: self

`fill()`#

public function fill(array<array-key, mixed> $values): self

Calls the method of every key with its value: ['name' => 'Consulting', 'quantity' => 4, 'netPrice' => '120.00']. An array value holds the arguments, as list or by name (['quantity' => [4, UnitCode::Hour]], ['allowance' => ['percent' => '10', 'reason' => 'Early bird']]); null values are skipped.

Parameter	Type	Description
`$values`	`array<array-key, mixed>`

Returns: self

`flushMacros()`#

public static function flushMacros(): void

static

`fromModel()`#

public function fromModel(ProvidesInvoiceLine $model): self

Lets an application model fill this line (ProvidesInvoiceLine::fillLine()).

Parameter	Type	Description
`$model`	`ProvidesInvoiceLine`

Returns: self

`group()`#

public function group(string $groupId): self

Assigns the line to a presentation group of the PDF (see InvoiceBuilder::group()).

Parameter	Type	Description
`$groupId`	`string`

Returns: self

`hasMacro()`#

public static function hasMacro(string $name): bool

static

Parameter	Type	Description
`$name`	`string`

Returns: bool

`hasPrice()`#

public function hasPrice(): bool

Whether a net price, list price or price including VAT was set.

Returns: bool

`hasVat()`#

public function hasVat(): bool

Whether vat() was called.

Returns: bool

`highlight()`#

public function highlight(bool $highlight = true): self

Highlights the line in the PDF and HTML (the default templates shade it and mark it in the secondary colour).

Parameter	Type	Description
`$highlight`	`bool` = `true`

Returns: self

`id()`#

public function id(string $id): self

Line identifier (BT-126); default the position, "1", "2", …

Parameter	Type	Description
`$id`	`string`

Returns: self

`lacksVat()`#

public function lacksVat(): bool

Whether the line or one of its sub lines has no VAT treatment yet.

Returns: bool

`listPrice()`#

public function listPrice(
    BigDecimal|int|float|string $grossPrice,
    BigDecimal|int|float|string|null $discount = null,
): self

List price before price discount (BT-148) and the discount per unit (BT-147). The net price is derived as list price minus discount unless set explicitly.

Parameter	Type	Description
`$grossPrice`	`Brick\Math\BigDecimal\|int\|float\|string`
`$discount`	`Brick\Math\BigDecimal\|int\|float\|string\|null` = `null`

Returns: self

`macro()`#

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

static

Parameter	Type	Description
`$name`	`string`
`$macro`	`callable`

`name()`#

public function name(string $name): self

Item name (BT-153). Required.

Parameter	Type	Description
`$name`	`string`

Returns: self

`netPrice()`#

public function netPrice(
    BigDecimal|int|float|string $price,
    BigDecimal|int|float|string|null $baseQuantity = null,
    UnitCode|RawCode|string|null $baseQuantityUnit = null,
): self

Net price per base quantity (BT-146, BT-149, BT-150).

Parameter	Type	Description
`$price`	`Brick\Math\BigDecimal\|int\|float\|string`
`$baseQuantity`	`Brick\Math\BigDecimal\|int\|float\|string\|null` = `null`
`$baseQuantityUnit`	`UnitCode\|RawCode\|string\|null` = `null`

Returns: self

`note()`#

public function note(?string $note): self

Line note (BT-127); null removes it.

Parameter	Type	Description
`$note`	`?string`

Returns: self

`objectId()`#

public function objectId(string $value, string|RawCode|null $scheme = null): self

Invoiced object identifier of the line (BT-128) with its scheme.

Parameter	Type	Description
`$value`	`string`
`$scheme`	`string\|RawCode\|null` = `null`

Returns: self

`orderLineReference()`#

public function orderLineReference(?string $reference): self

Line of the purchase order (BT-132); null removes it.

Parameter	Type	Description
`$reference`	`?string`

Returns: self

`originCountry()`#

public function originCountry(?string $country): self

Country of origin of the item (BT-159), ISO 3166-1 alpha-2, uppercased; null removes it.

Parameter	Type	Description
`$country`	`?string`

Returns: self

`period()`#

public function period(Date|string|null $start, Date|string|null $end = null): self

Line period (BG-26): start (BT-134) and end (BT-135); one of them may be null.

Parameter	Type	Description
`$start`	`Date\|string\|null`
`$end`	`Date\|string\|null` = `null`

Returns: self

`priceInclVat()`#

public function priceInclVat(BigDecimal|int|float|string $price): self

Price including VAT (gross price mode for B2C and shops). The calculator derives the net price so that the customer pays exactly the gross amount.

Parameter	Type	Description
`$price`	`Brick\Math\BigDecimal\|int\|float\|string`

Returns: self

`quantity()`#

public function quantity(
    BigDecimal|int|float|string $quantity,
    UnitCode|RawCode|string|null $unit = null,
): self

Invoiced quantity (BT-129), optionally with the unit (BT-130); default 1. Negative quantities for returns and discounts.

Parameter	Type	Description
`$quantity`	`Brick\Math\BigDecimal\|int\|float\|string`
`$unit`	`UnitCode\|RawCode\|string\|null` = `null`

Returns: self
Throws: InvalidArgumentException – for a float

`reference()`#

public function reference(DocumentReference $reference): self

Adds a reference to an order, contract, despatch or receiving advice or another document (profile EXTENDED only).

Parameter	Type	Description
`$reference`	`DocumentReference`

Returns: self

`sellerId()`#

public function sellerId(?string $id): self

The seller's item number (BT-155); null removes it.

Parameter	Type	Description
`$id`	`?string`

Returns: self

`showGrossPrice()`#

public function showGrossPrice(?bool $show = true): self

Prints the price including VAT below the net unit price of this line (true) or not (false), whatever Presentation::$showGrossPrices says for the invoice; null follows the presentation again. It is printed only for lines with a price including VAT (priceInclVat()).

Parameter	Type	Description
`$show`	`?bool` = `true`

Returns: self

`standardId()`#

public function standardId(
    string $value,
    IdentifierScheme|RawCode|string $scheme = \Quittio\Core\Enums\IdentifierScheme::Gtin,
): self

Standard item identifier (BT-157) with its scheme (BT-157-1); default scheme GTIN (0160).

Parameter	Type	Description
`$value`	`string`
`$scheme`	`IdentifierScheme\|RawCode\|string` = `\Quittio\Core\Enums\IdentifierScheme::Gtin`

Returns: self

`subLine()`#

public function subLine(
    self|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,
): self

Adds a sub line (profile EXTENDED or XRechnung extension), in the forms of InvoiceBuilder::line(): a name with the common values, Line::make(), an array, a model or a callable.

Parameter	Type	Description
`$line`	`self\|ProvidesInvoiceLine\|array\|callable\|string`
`$netPrice`	`Brick\Math\BigDecimal\|int\|float\|string\|null` = `null`
`$quantity`	`Brick\Math\BigDecimal\|int\|float\|string\|null` = `null`
`$unit`	`UnitCode\|RawCode\|string\|null` = `null`
`$vat`	`TaxPreset\|VatCategory\|null` = `null`
`$description`	`?string` = `null`
`$priceInclVat`	`Brick\Math\BigDecimal\|int\|float\|string\|null` = `null`

Returns: self

`unit()`#

public function unit(UnitCode|RawCode|string $unit): self

Unit of the quantity (BT-130), UN/ECE Recommendation 20/21; default C62 (one). Unknown codes are kept as RawCode.

Parameter	Type	Description
`$unit`	`UnitCode\|RawCode\|string`

Returns: self

`vat()`#

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

Sets the VAT treatment, either via a preset of a country pack or as category and rate.

Parameter	Type	Description
`$presetOrCategory`	`TaxPreset\|VatCategory`
`$rate`	`Brick\Math\BigDecimal\|int\|float\|string\|null` = `null`
`$exemptionReason`	`?string` = `null`
`$exemptionReasonCode`	`VatExemptionReasonCode\|RawCode\|string\|null` = `null`

Returns: self

LineBuilder

Constants#

Properties#

Methods#

__call()#

allowance()#

attribute()#

build()#

buyerAccountingReference()#

buyerId()#

charge()#

classification()#

description()#

explicitId()#

extended()#

fill()#

flushMacros()#

fromModel()#

group()#

hasMacro()#

hasPrice()#

hasVat()#

highlight()#

id()#

lacksVat()#

listPrice()#

macro()#

name()#

netPrice()#

note()#

objectId()#

orderLineReference()#

originCountry()#

period()#

priceInclVat()#

quantity()#

reference()#

sellerId()#

showGrossPrice()#

standardId()#

subLine()#

unit()#

vat()#

`__call()`#

`allowance()`#

`attribute()`#

`build()`#

`buyerAccountingReference()`#

`buyerId()`#

`charge()`#

`classification()`#

`description()`#

`explicitId()`#

`extended()`#

`fill()`#

`flushMacros()`#

`fromModel()`#

`group()`#

`hasMacro()`#

`hasPrice()`#

`hasVat()`#

`highlight()`#

`id()`#

`lacksVat()`#

`listPrice()`#

`macro()`#

`name()`#

`netPrice()`#

`note()`#

`objectId()`#

`orderLineReference()`#

`originCountry()`#

`period()`#

`priceInclVat()`#

`quantity()`#

`reference()`#

`sellerId()`#

`showGrossPrice()`#

`standardId()`#

`subLine()`#

`unit()`#

`vat()`#