CoolCMS API

PaymentForm extends BaseComponent
in package
uses FormTrait, PriceTrait

Table of Contents

Constants

FLAG_VAT_ID_NOT_VERIFIED  : string = 'VAT_ID_NOT_VERIFIED'
Engine flag "VAT id filled in but not verified within 30 days" (`TaxFlag::VatIdNotVerified`).
MONEY_SCALE  : int = 3
Money output: scale of the `decimal(10,3)` columns (mirrors `InvoiceCalculator::MONEY_SCALE`).
WORK_SCALE  : int = 12
Intermediate computations (money and rates): mirrors `InvoiceCalculator::WORK_SCALE`.

Properties

$container  : Container
$routerDispatcher  : RouterDispatcher
$translator  : ITranslator
$appContext  : AppContext
$componentParameters  : array<string, mixed>
$currencyContext  : CurrencyContext|null
$deviceDetector  : DeviceDetector|null
$languageContext  : LanguageContext|null
$localizationContext  : LocalizationContext|null
$settingContext  : SettingContext
$themeContext  : ThemeContext|null
$translatorDomain  : string|null
$callbackKey  : string|null
$currency  : object|null
$defaultEmail  : string|null
$heading  : string|null
$itemGroups  : array<string, array<int, PaymentFormItemDTO>>
$onSuccessRedirect  : callable|null
$paymentCallbackManager  : PaymentCallbackManager
$paymentDescriptionPrefix  : string|null
$paymentGateId  : int|null
$paymentGateList  : array<int, PaymentGate>
$paymentItemSaver  : callable|null
$paymentManager  : PaymentManager
$paymentName  : string|null
$paymentRegion  : object|null
$tariffExtraRenderer  : callable|null
$taxCustomer  : PaymentFormTaxCustomerDTO|null
Customer for the engine; null means it is loaded from the logged-in user ({@see getTaxCustomer()}).
$taxOnSubmit  : bool
Form submit is the tax point, so the VAT id check runs as `refresh_stale` (online VIES at most once a day). Render and autoupdate read only the records (`cache_only`), so a redraw never calls VIES.
$userManager  : UserManager

Methods

__call()  : mixed
Dispatches `renderXyz()` to `render('Xyz', ...$args)`.
__construct()  : mixed
createComponent()  : IComponent|null
getAppContext()  : AppContext
getComponentParameter()  : mixed
Returns a component parameter, or null when it is not set.
getContainer()  : Container
getCurrencyContext()  : CurrencyContext|null
getLanguageContext()  : LanguageContext|null
getLocalizationContext()  : LocalizationContext|null
getRouterDispatcher()  : RouterDispatcher
getSelectedPaymentGateId()  : int|null
getSettingContext()  : SettingContext
getSettings()  : array<int, array<string, mixed>>
getThemeContext()  : ThemeContext|null
hasServiceByType()  : bool
Returns whether the container has a service of the given type.
initializeAllContexts()  : void
injectDeviceDetector()  : void
onCreate()  : void
onSubmit()  : void
onSuccess()  : void
render()  : void
setAppContext()  : $this
setCallbackKey()  : self
setComponentParameter()  : void
Sets a component parameter.
setCurrency()  : self
setCurrencyContext()  : $this
setDefaultEmail()  : self
setHeading()  : self
setItemGroups()  : self
setLanguageContext()  : $this
setLocalizationContext()  : $this
setOnSuccessRedirect()  : self
setPaymentDescriptionPrefix()  : self
setPaymentGateList()  : self
setPaymentItemSaver()  : self
setPaymentName()  : self
setPaymentRegion()  : self
setSettingContext()  : $this
setTariffExtraRenderer()  : self
setTaxCustomer()  : self
Sets the customer for the VAT engine explicitly (harness, a future payment for a foreign account); without the call the logged-in user is read.
setThemeContext()  : $this
setup()  : void
setupAppContext()  : void
typedComponent()  : T
Returns a subcomponent with a verified type.
createComponentForm()  : Form
frontPresenter()  : BasePresenter|null
Returns the front presenter the component is attached to (null outside the front end or when detached).
getTranslator()  : ITranslator
setTemplateFile()  : void
setTranslator()  : self
applyTaxSnapshot()  : void
Tax snapshot of the payment: treatment code, date, rate country, clause, customer country, VAT id verification, flags and commodity code from the engine response at submit ({@see PriceTrait::buildTaxSnapshot()}). The invoice takes it over ({@see \App\UI\Api\Invoicer\Models\Generators\InvoiceGenerator}); an intermediary gate and credits carry only a marker (`INTERMEDIARY` / `CREDIT_REDEMPTION`) and produce no invoice.
applyVat()  : numeric-string
Converts a base to an amount with VAT, or returns the base unchanged. Mirrors the invoice line ({@see \App\UI\Api\Invoicer\Models\Helpers\InvoiceCalculator::recalculateLine()}): the base is first rounded to money and then multiplied by the rate; the result stays unrounded (`WORK_SCALE`).
buildGateFeeParts()  : array{price: string, percents: int, percentsPrice: string, total: string}
Returns the gate fee breakdown for the `payment_gate_fee_*` payment columns. All values are bases without VAT.
buildItemPrices()  : array<string, array<int, array{display: float, charged: float, base: float, withVat: bool}>>
Returns prices of the offered items for the template (the form shows what will be on the invoice): `charged` = charged price (also goes to `data-price`), `display` = the same, `base` = base without VAT, `withVat` = VAT is charged (the template then shows the base next to the price).
buildPaymentItemSnapshot()  : array<int, PaymentItem>
Builds the snapshot from the selected paid items, from the same engine response that was charged ({@see PriceTrait::buildTaxedItems()}): base without VAT (a final price is split from the top), the engine rate (0 = no VAT charged) and the supply kind. A marked gate (SMS via intermediary, credits) means price 1:1 and rate 0; no invoice arises from such a payment.
buildPaymentItemSnapshotMeta()  : array<int, array{name: string, price: string, vatPercents: ?string, productTypeId: ?int, supplyKindId: ?int, sort: int}>
Accounting snapshot of the charged payment items (`cms_system_payment_items`) as `meta` rows of the payment insert: name, base, VAT rate and productType exactly as charged now. The invoice builds its lines from it ({@see \App\UI\Api\Invoicer\Models\Generators\InvoiceGenerator::addLinesFromPayment()}) and prefers it over the live price list, which may change between checkout and invoicing; the snapshot may not. Not to be confused with the activation `cms_mod_*_payment_items`, which the module saves through `paymentItemSaver`.
buildTaxedItems()  : array<int, PaymentFormItemPriceDTO}, base: string, vatPercents: numeric-string, supplyKindId: int|null}>
Returns the item snapshot from the engine response: base without VAT (a final price is split from the top), rate (0 = no VAT charged) and the supply kind as the engine used it (the default is filled in by the bridge).
buildTaxSnapshot()  : DateTime|null, customerVatIdCheckId: int|null, customerVatIdOutageCheckId: int|null, taxFlags: list|null, summaryReportCode: string|null}
Returns the tax snapshot of the payment from the engine response for the selected items: main-supply treatment code, date, rate country, clause, customer country, VAT id verification, flags, commodity code. A marked gate (SMS via intermediary, credits) gives only the marker and the date.
collectPricedItems()  : array<int, PaymentFormItemPriceDTO}>
Returns paid items with a price for the gate: all offered ones (`$values` null, display) or only those selected in the form. Order = row index in the engine response.
computeGateFeeChargedPrice()  : float
Returns the charged gate fee rounded to money, for `data-price`.
computeGateFeeFixedDisplayPrice()  : float
Returns the fixed part of the gate fee for display (for example a percentage plus a fixed amount). For a VAT payer it follows the treatment of the offer's main supply; the percentage part is shown as a rate.
computeGateFeeGrossPrice()  : numeric-string
Returns the unrounded charged intermediate of the gate fee: the sum of shares split by the engine (`share base x (1 + group rate)` for `chargeVat`), exactly the fee lines the invoice builds from `payment.payment_gate_fee_total`. Final prices, a gate marker or no engine response give the fee base.
computeGateFeePercentsPrice()  : numeric-string
Returns the percentage part of the gate fee from the tariff base, unrounded (`WORK_SCALE`).
computeGateFeePrice()  : numeric-string
Returns the gate fee as a base without VAT (percentage of tariff bases + fixed amount) rounded to money; stored in `payment.payment_gate_fee_total`, and the invoice builds the fee lines from it.
computeItemGrossPrice()  : numeric-string
Returns the unrounded charged intermediate of an item, exactly what the invoice adds for the line.
computeTariffsBasePrice()  : numeric-string
Returns the sum of bases of the selected fee-bearing items, the basis of the percentage part of the gate fee.
computeTotalPrice()  : float
Returns the amount the customer actually pays; it goes to `payment.total_price` and from there 1:1 to the gate. Unrounded line intermediates (scale 12) are summed and the sum is rounded in one step to the currency precision ({@see roundToPrecision()}); gates with final prices go 1:1 to 3 places.
createMultiplierComponent()  : Multiplier<string|int, IComponent>
Creates a multiplier for the component.
createNewComponentInstance()  : IComponent|null
Creates a new component instance without adding it to the presenter; used by the multiplier.
createNewPayment()  : Payment|null}
createStandardComponent()  : IComponent|null
Creates a standard component (not a multiplier).
fetchTaxResolution()  : array<string, mixed>
Returns the engine response for the items. An empty array means the engine is not called (gate marker, no item) or the bridge failed; {@see isTaxUnavailable()} tells them apart.
findContributteTranslator()  : Translator|null
findDocumentLocale()  : string
Locale of the payment texts is the page language (fallback Czech).
findGateFeeRel()  : PaymentGateRegionRel|null
Returns the selected gate relation to the payment region when its fee is on; otherwise null.
findNumeric()  : numeric-string
Returns a numeric value from the bridge response as a numeric-string, otherwise `$default`.
findPaymentGate()  : PaymentGate|null
Gate from the list offered by the form.
findTaxLine()  : array<string, mixed>|null
Returns the engine response line for the item at the given index; null when the engine was not called or failed.
findTaxPercents()  : numeric-string
Returns the treatment rate as a `DECIMAL(5,2)` string ('21.00', '5.50'), the shape of the invoice line (`InvoiceItem.vat`).
getCurrencyPrecision()  : int
Returns the number of decimal places of the payable amount (`cms_system_currencies.precision`).
getDisplayTaxResolution()  : array<string, mixed>
getFirstPaymentGateId()  : int|null
getFormValues()  : ArrayHash
getItemGroups()  : array<string, array<int, PaymentFormItemDTO>>
getPaymentRegionId()  : int|null
Price-list axes of the form: payment region id and currency id. The component holds them as `?object` (set by the module presenter); the docblock only narrows them.
getPriceCurrencyId()  : int|null
Returns the price-list axis for the given gate: the currency of the gate's region relation, falling back to the form currency ({@see resolveGateCurrency()}). The admin price list keeps the same rule when saving rows (`TariffFormTrait::buildTariffPrices()`) and so does `PaymentFormPageTrait::prepareCurrency()`.
getSelectedTaxResolution()  : array<string, mixed>
getTaxCustomer()  : PaymentFormTaxCustomerDTO
Returns the customer for the engine: the logged-in user's ISO country, company (`isCompany` or a filled company), VAT id and registration number. An anonymous user or an unloaded profile gives an empty customer (consumer in the region country).
hasSelectedItem()  : bool
At least one item of any group is selected.
isFinalPriceGate()  : bool
Tells whether the gate has final prices; VAT top-up and the final rounding to currency precision are forbidden for it: the data flag `cms_system_payment_gates.final_prices` (checkbox in the gate admin), or a price list in a non-monetary currency (`currencies.monetary = 0`, credits), where VAT is not handled over units. The admin tariff price list keeps the same rule (`Tariff/edit.latte`, `$isFinal`).
isNonMonetaryGate()  : bool
The price list of the selected gate is in a non-monetary currency (credits).
isSelectionPurchasable()  : bool
IMPORTANT: server-side check of the selection. The template forbids unpurchasable items only with the HTML attribute `disabled`, and the server used to accept every offered id: an item without an active price for (region, gate, currency) was left out of the sum (price 0) yet stored as an activation, so after "paying" zero it activated for free (a credit package gave credits without payment).
isTaxResolutionUsable()  : bool
Tells whether the engine response is usable: lines without errors (a missing rate or supply kind makes it unusable).
isTaxUnavailable()  : bool
The engine should have been called for the gate but gave no usable response, so prices are unreliable.
isVatChargedOn()  : bool
Tells whether the engine charges VAT for a response line or share (`treatment.chargeVat` of the line, `chargeVat` of the share).
money()  : numeric-string
Converts to a money value for `decimal(10,3)`, half-up; a copy of `InvoiceCalculator::money()` (bcmath truncates, hence +0.0005; for negatives -0.0005).
normalizePaymentGateId()  : void
num()  : numeric-string
Converts an entity or DTO value to a numeric-string safe for bcmath; a copy of `InvoiceCalculator::num()`.
resolveFinalPriceNoteKey()  : string|null
Returns the note key for a final-prices gate, `price.vatNoteFinal.<script_name>`, but only when the translation exists; otherwise `null` (`{_$vatNoteKey}` on a missing key would print the bare key).
resolveGateCurrency()  : object|null
Returns the display currency of the selected gate: the currency of the gate prices for this payment region (`payment_gate_region_relations.currency_id`). A credit gate has its price list in a non-monetary currency (`KRD`).
resolveGateId()  : int
Gate id from the form values (0 = not selected).
resolveTaxMarker()  : string|null
Returns the payment marker for which the engine is not called and no invoice arises for the customer, otherwise null: intermediary gate gives `INTERMEDIARY`; a price list in a non-monetary currency gives `CREDIT_REDEMPTION`.
resolveTaxNote()  : string|null
Returns the VAT treatment clause (identified person, non-payer, "tax paid by the customer", outside the domestic scope) in the page language and, below it, in Czech; null when none applies (domestic payer, gate marker, engine failed).
resolveVatIdNoticeKey()  : string|null
Returns the message "VAT id not verified within the last 30 days" when the engine treated a company with an EU VAT id as a consumer (flag `VAT_ID_NOT_VERIFIED`); otherwise null.
resolveVatNoteKey()  : string|null
Returns the key of the VAT note under the price list (translation domain of the component), or `null`: - gate with final prices: its own text `price.vatNoteFinal.<script_name>` (only if it exists), - the engine charges VAT (payer): "Prices include VAT.", - otherwise nothing; identified person, non-payer and reverse charge carry a clause instead ({@see resolveTaxNote()}).
roundToPrecision()  : numeric-string
IMPORTANT: final rounding of the payable amount to the currency precision, half away from zero, with the same semantics as {@see money()} at `p` places. `p >= MONEY_SCALE` equals {@see money()}. Call it on the unrounded sum, otherwise the amount is rounded twice.
setDefaults()  : void
translationExists()  : bool
Tells whether the translation catalog has a key relative to the component domain. The key is composed like `{_'key'}` in the template (component domain + dot + key); {@see TranslationHelpers::extractMessage()} is the same method that {@see ContributteTranslator::translate()} uses.
vatMultiplier()  : numeric-string
Returns the VAT multiplier `1 + rate/100`; a copy of `InvoiceCalculator::vatMultiplier()`.

Constants

FLAG_VAT_ID_NOT_VERIFIED

Engine flag "VAT id filled in but not verified within 30 days" (`TaxFlag::VatIdNotVerified`).

private string FLAG_VAT_ID_NOT_VERIFIED = 'VAT_ID_NOT_VERIFIED'

MONEY_SCALE

Money output: scale of the `decimal(10,3)` columns (mirrors `InvoiceCalculator::MONEY_SCALE`).

private int MONEY_SCALE = 3

WORK_SCALE

Intermediate computations (money and rates): mirrors `InvoiceCalculator::WORK_SCALE`.

private int WORK_SCALE = 12

Properties

$componentParameters

protected array<string, mixed> $componentParameters = []

component parameters set by setComponentParameter()

$translatorDomain

protected string|null $translatorDomain = 'front.base.components.paymentForm'

$callbackKey

private string|null $callbackKey = null

$defaultEmail

private string|null $defaultEmail = null

$onSuccessRedirect

private callable|null $onSuccessRedirect = null

$paymentDescriptionPrefix

private string|null $paymentDescriptionPrefix = null

$paymentGateId

private int|null $paymentGateId = null

$paymentItemSaver

private callable|null $paymentItemSaver = null

$paymentName

private string|null $paymentName = null

$paymentRegion

private object|null $paymentRegion = null

$tariffExtraRenderer

private callable|null $tariffExtraRenderer = null

$taxOnSubmit

Form submit is the tax point, so the VAT id check runs as `refresh_stale` (online VIES at most once a day). Render and autoupdate read only the records (`cache_only`), so a redraw never calls VIES.

private bool $taxOnSubmit = false

Methods

__call()

Dispatches `renderXyz()` to `render('Xyz', ...$args)`.

public __call(string $name, array<string|int, mixed> $args) : mixed

Called only when the component has no renderXyz() method of its own.

Parameters
$name : string
$args : array<string|int, mixed>

createComponent()

public createComponent(string $name) : IComponent|null
Parameters
$name : string
Return values
IComponent|null

getComponentParameter()

Returns a component parameter, or null when it is not set.

public getComponentParameter(string $name) : mixed
Parameters
$name : string

getContainer()

public getContainer() : Container
Return values
Container

getSelectedPaymentGateId()

public getSelectedPaymentGateId() : int|null
Return values
int|null

getSettings()

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

hasServiceByType()

Returns whether the container has a service of the given type.

public hasServiceByType(string $className) : bool

The name is composed dynamically (module plus component), so class_exists() runs first, and a true result guarantees a valid type.

Parameters
$className : string
Tags
phpstan-assert-if-true

class-string $className

Return values
bool

onSuccess()

public onSuccess(Form $form, ArrayHash $values) : void
Parameters
$form : Form
$values : ArrayHash

setCallbackKey()

public setCallbackKey(string $key) : self
Parameters
$key : string
Return values
self

setComponentParameter()

Sets a component parameter.

public setComponentParameter(string $name, mixed $value) : void
Parameters
$name : string
$value : mixed

setCurrency()

public setCurrency(object|null $currency) : self
Parameters
$currency : object|null
Return values
self

setDefaultEmail()

public setDefaultEmail(string|null $email) : self
Parameters
$email : string|null
Return values
self

setHeading()

public setHeading(string|null $heading) : self
Parameters
$heading : string|null
Return values
self

setOnSuccessRedirect()

public setOnSuccessRedirect(callable $cb) : self
Parameters
$cb : callable
Return values
self

setPaymentDescriptionPrefix()

public setPaymentDescriptionPrefix(string $prefix) : self
Parameters
$prefix : string
Return values
self

setPaymentGateList()

public setPaymentGateList(array<int, PaymentGate> $paymentGateList) : self
Parameters
$paymentGateList : array<int, PaymentGate>
Return values
self

setPaymentItemSaver()

public setPaymentItemSaver(callable $cb) : self
Parameters
$cb : callable
Return values
self

setPaymentName()

public setPaymentName(string $name) : self
Parameters
$name : string
Return values
self

setPaymentRegion()

public setPaymentRegion(object|null $paymentRegion) : self
Parameters
$paymentRegion : object|null
Return values
self

setTariffExtraRenderer()

public setTariffExtraRenderer(callable|null $cb) : self
Parameters
$cb : callable|null
Return values
self

setTaxCustomer()

Sets the customer for the VAT engine explicitly (harness, a future payment for a foreign account); without the call the logged-in user is read.

public setTaxCustomer(PaymentFormTaxCustomerDTO|null $taxCustomer) : self
Parameters
$taxCustomer : PaymentFormTaxCustomerDTO|null
Return values
self

typedComponent()

Returns a subcomponent with a verified type.

public typedComponent(string $name, T> $type) : T

Use it instead of an inline @var above $this['x'] (which does not narrow the type) and instead of the generic IComponent that $this['x'] returns. See Form::typedComponent().

Parameters
$name : string
$type : T>
Tags
template
Return values
T

frontPresenter()

Returns the front presenter the component is attached to (null outside the front end or when detached).

protected frontPresenter() : BasePresenter|null
Return values
BasePresenter|null

getTranslator()

protected getTranslator() : ITranslator
Return values
ITranslator

setTemplateFile()

protected setTemplateFile(string $dir, string $filename) : void
Parameters
$dir : string
$filename : string

setTranslator()

protected setTranslator(ITranslator $translator) : self
Parameters
$translator : ITranslator
Return values
self

applyTaxSnapshot()

Tax snapshot of the payment: treatment code, date, rate country, clause, customer country, VAT id verification, flags and commodity code from the engine response at submit ({@see PriceTrait::buildTaxSnapshot()}). The invoice takes it over ({@see \App\UI\Api\Invoicer\Models\Generators\InvoiceGenerator}); an intermediary gate and credits carry only a marker (`INTERMEDIARY` / `CREDIT_REDEMPTION`) and produce no invoice.

private applyTaxSnapshot(Payment $payment, ArrayHash $values) : void
Parameters
$payment : Payment
$values : ArrayHash

applyVat()

Converts a base to an amount with VAT, or returns the base unchanged. Mirrors the invoice line ({@see \App\UI\Api\Invoicer\Models\Helpers\InvoiceCalculator::recalculateLine()}): the base is first rounded to money and then multiplied by the rate; the result stays unrounded (`WORK_SCALE`).

private applyVat(numeric-string $base, numeric-string $vatPercents, bool $withVat) : numeric-string
Parameters
$base : numeric-string
$vatPercents : numeric-string
$withVat : bool
Return values
numeric-string

buildGateFeeParts()

Returns the gate fee breakdown for the `payment_gate_fee_*` payment columns. All values are bases without VAT.

private buildGateFeeParts(ArrayHash $values) : array{price: string, percents: int, percentsPrice: string, total: string}
Parameters
$values : ArrayHash
Return values
array{price: string, percents: int, percentsPrice: string, total: string}

buildItemPrices()

Returns prices of the offered items for the template (the form shows what will be on the invoice): `charged` = charged price (also goes to `data-price`), `display` = the same, `base` = base without VAT, `withVat` = VAT is charged (the template then shows the base next to the price).

private buildItemPrices(int|null $paymentGateId) : array<string, array<int, array{display: float, charged: float, base: float, withVat: bool}>>
Parameters
$paymentGateId : int|null
Return values
array<string, array<int, array{display: float, charged: float, base: float, withVat: bool}>>

buildPaymentItemSnapshot()

Builds the snapshot from the selected paid items, from the same engine response that was charged ({@see PriceTrait::buildTaxedItems()}): base without VAT (a final price is split from the top), the engine rate (0 = no VAT charged) and the supply kind. A marked gate (SMS via intermediary, credits) means price 1:1 and rate 0; no invoice arises from such a payment.

private buildPaymentItemSnapshot(ArrayHash $values) : array<int, PaymentItem>
Parameters
$values : ArrayHash
Return values
array<int, PaymentItem>

buildPaymentItemSnapshotMeta()

Accounting snapshot of the charged payment items (`cms_system_payment_items`) as `meta` rows of the payment insert: name, base, VAT rate and productType exactly as charged now. The invoice builds its lines from it ({@see \App\UI\Api\Invoicer\Models\Generators\InvoiceGenerator::addLinesFromPayment()}) and prefers it over the live price list, which may change between checkout and invoicing; the snapshot may not. Not to be confused with the activation `cms_mod_*_payment_items`, which the module saves through `paymentItemSaver`.

private buildPaymentItemSnapshotMeta(ArrayHash $values) : array<int, array{name: string, price: string, vatPercents: ?string, productTypeId: ?int, supplyKindId: ?int, sort: int}>

IMPORTANT: the Api saves the rows in the payment transaction, so a snapshot failure means no payment (the form shows an error), never a payment with part of its snapshot.

Parameters
$values : ArrayHash
Return values
array<int, array{name: string, price: string, vatPercents: ?string, productTypeId: ?int, supplyKindId: ?int, sort: int}>

buildTaxedItems()

Returns the item snapshot from the engine response: base without VAT (a final price is split from the top), rate (0 = no VAT charged) and the supply kind as the engine used it (the default is filled in by the bridge).

private buildTaxedItems(ArrayHash $values) : array<int, PaymentFormItemPriceDTO}, base: string, vatPercents: numeric-string, supplyKindId: int|null}>
Parameters
$values : ArrayHash
Return values
array<int, PaymentFormItemPriceDTO}, base: string, vatPercents: numeric-string, supplyKindId: int|null}>

buildTaxSnapshot()

Returns the tax snapshot of the payment from the engine response for the selected items: main-supply treatment code, date, rate country, clause, customer country, VAT id verification, flags, commodity code. A marked gate (SMS via intermediary, credits) gives only the marker and the date.

private buildTaxSnapshot(ArrayHash $values) : DateTime|null, customerVatIdCheckId: int|null, customerVatIdOutageCheckId: int|null, taxFlags: list|null, summaryReportCode: string|null}
Parameters
$values : ArrayHash
Return values
DateTime|null, customerVatIdCheckId: int|null, customerVatIdOutageCheckId: int|null, taxFlags: list|null, summaryReportCode: string|null}

collectPricedItems()

Returns paid items with a price for the gate: all offered ones (`$values` null, display) or only those selected in the form. Order = row index in the engine response.

private collectPricedItems(int|null $paymentGateId, ArrayHash|null $values) : array<int, PaymentFormItemPriceDTO}>
Parameters
$paymentGateId : int|null
$values : ArrayHash|null
Return values
array<int, PaymentFormItemPriceDTO}>

computeGateFeeChargedPrice()

Returns the charged gate fee rounded to money, for `data-price`.

private computeGateFeeChargedPrice(ArrayHash $values) : float
Parameters
$values : ArrayHash
Return values
float

computeGateFeeFixedDisplayPrice()

Returns the fixed part of the gate fee for display (for example a percentage plus a fixed amount). For a VAT payer it follows the treatment of the offer's main supply; the percentage part is shown as a rate.

private computeGateFeeFixedDisplayPrice(int|null $paymentGateId) : float
Parameters
$paymentGateId : int|null
Return values
float

computeGateFeeGrossPrice()

Returns the unrounded charged intermediate of the gate fee: the sum of shares split by the engine (`share base x (1 + group rate)` for `chargeVat`), exactly the fee lines the invoice builds from `payment.payment_gate_fee_total`. Final prices, a gate marker or no engine response give the fee base.

private computeGateFeeGrossPrice(ArrayHash $values) : numeric-string
Parameters
$values : ArrayHash
Return values
numeric-string

computeGateFeePercentsPrice()

Returns the percentage part of the gate fee from the tariff base, unrounded (`WORK_SCALE`).

private computeGateFeePercentsPrice(ArrayHash $values, PaymentGateRegionRel $rel) : numeric-string
Parameters
$values : ArrayHash
$rel : PaymentGateRegionRel
Return values
numeric-string

computeGateFeePrice()

Returns the gate fee as a base without VAT (percentage of tariff bases + fixed amount) rounded to money; stored in `payment.payment_gate_fee_total`, and the invoice builds the fee lines from it.

private computeGateFeePrice(ArrayHash $values) : numeric-string
Parameters
$values : ArrayHash
Return values
numeric-string

computeItemGrossPrice()

Returns the unrounded charged intermediate of an item, exactly what the invoice adds for the line.

private computeItemGrossPrice(PaymentFormItemPriceDTO $price, array<string, mixed>|null $taxLine, bool $finalPrice) : numeric-string

A final price (final_prices gate, grossPrice) is the price 1:1; base x (1 + rate) only when the engine said chargeVat. Without an engine response it is the base (the submit is then rejected).

Parameters
$price : PaymentFormItemPriceDTO
$taxLine : array<string, mixed>|null
$finalPrice : bool
Return values
numeric-string

computeTariffsBasePrice()

Returns the sum of bases of the selected fee-bearing items, the basis of the percentage part of the gate fee.

private computeTariffsBasePrice(ArrayHash $values) : numeric-string
Parameters
$values : ArrayHash
Return values
numeric-string

computeTotalPrice()

Returns the amount the customer actually pays; it goes to `payment.total_price` and from there 1:1 to the gate. Unrounded line intermediates (scale 12) are summed and the sum is rounded in one step to the currency precision ({@see roundToPrecision()}); gates with final prices go 1:1 to 3 places.

private computeTotalPrice(ArrayHash $values) : float
Parameters
$values : ArrayHash
Return values
float

createMultiplierComponent()

Creates a multiplier for the component.

private createMultiplierComponent(string $name) : Multiplier<string|int, IComponent>
Parameters
$name : string
Return values
Multiplier<string|int, IComponent>

createNewComponentInstance()

Creates a new component instance without adding it to the presenter; used by the multiplier.

private createNewComponentInstance(string $baseName[, int|string|null $uniqueKey = null ]) : IComponent|null
Parameters
$baseName : string
$uniqueKey : int|string|null = null
Return values
IComponent|null

createNewPayment()

private createNewPayment(ArrayHash $values, int $paymentGateId, float $totalPrice) : Payment|null}
Parameters
$values : ArrayHash
$paymentGateId : int
$totalPrice : float
Return values
Payment|null}

createStandardComponent()

Creates a standard component (not a multiplier).

private createStandardComponent(string $name) : IComponent|null
Parameters
$name : string
Return values
IComponent|null

fetchTaxResolution()

Returns the engine response for the items. An empty array means the engine is not called (gate marker, no item) or the bridge failed; {@see isTaxUnavailable()} tells them apart.

private fetchTaxResolution(array<int, PaymentFormItemPriceDTO}> $entries, int|null $paymentGateId[, numeric-string|null $ancillary = null ]) : array<string, mixed>
Parameters
$entries : array<int, PaymentFormItemPriceDTO}>
$paymentGateId : int|null
$ancillary : numeric-string|null = null

base of the ancillary supply (gate fee) to split

Return values
array<string, mixed>

findContributteTranslator()

private findContributteTranslator() : Translator|null
Return values
Translator|null

findDocumentLocale()

Locale of the payment texts is the page language (fallback Czech).

private findDocumentLocale() : string
Return values
string

findGateFeeRel()

Returns the selected gate relation to the payment region when its fee is on; otherwise null.

private findGateFeeRel(int|null $paymentGateId) : PaymentGateRegionRel|null
Parameters
$paymentGateId : int|null
Return values
PaymentGateRegionRel|null

findNumeric()

Returns a numeric value from the bridge response as a numeric-string, otherwise `$default`.

private findNumeric(mixed $value[, numeric-string $default = '0' ]) : numeric-string
Parameters
$value : mixed
$default : numeric-string = '0'
Return values
numeric-string

findPaymentGate()

Gate from the list offered by the form.

private findPaymentGate(int|null $paymentGateId) : PaymentGate|null
Parameters
$paymentGateId : int|null
Return values
PaymentGate|null

findTaxLine()

Returns the engine response line for the item at the given index; null when the engine was not called or failed.

private findTaxLine(array<string, mixed> $resolution, int $index) : array<string, mixed>|null
Parameters
$resolution : array<string, mixed>
$index : int
Return values
array<string, mixed>|null

findTaxPercents()

Returns the treatment rate as a `DECIMAL(5,2)` string ('21.00', '5.50'), the shape of the invoice line (`InvoiceItem.vat`).

private findTaxPercents(mixed $treatment) : numeric-string

IMPORTANT: never round it to a whole number; a decimal rate (5.5 %) would misprice the item.

Parameters
$treatment : mixed
Return values
numeric-string

getCurrencyPrecision()

Returns the number of decimal places of the payable amount (`cms_system_currencies.precision`).

private getCurrencyPrecision() : int

Without a currency the money scale of the decimal(10,3) column applies.

Return values
int

getDisplayTaxResolution()

private getDisplayTaxResolution(int|null $paymentGateId) : array<string, mixed>
Parameters
$paymentGateId : int|null
Return values
array<string, mixed> —

engine response for all offered items (price display)

getFirstPaymentGateId()

private getFirstPaymentGateId() : int|null
Return values
int|null

getFormValues()

private getFormValues(Form $form) : ArrayHash
Parameters
$form : Form
Return values
ArrayHash

getPaymentRegionId()

Price-list axes of the form: payment region id and currency id. The component holds them as `?object` (set by the module presenter); the docblock only narrows them.

private getPaymentRegionId() : int|null
Return values
int|null

getPriceCurrencyId()

Returns the price-list axis for the given gate: the currency of the gate's region relation, falling back to the form currency ({@see resolveGateCurrency()}). The admin price list keeps the same rule when saving rows (`TariffFormTrait::buildTariffPrices()`) and so does `PaymentFormPageTrait::prepareCurrency()`.

private getPriceCurrencyId(int|null $paymentGateId) : int|null

IMPORTANT: do not derive it from $this->currency directly. The component receives that currency from the presenter as a snapshot taken at creation, and it differs between render and submit.

Parameters
$paymentGateId : int|null
Return values
int|null

getSelectedTaxResolution()

private getSelectedTaxResolution(ArrayHash $values) : array<string, mixed>
Parameters
$values : ArrayHash
Return values
array<string, mixed> —

engine response for the selected items + the split gate fee

getTaxCustomer()

Returns the customer for the engine: the logged-in user's ISO country, company (`isCompany` or a filled company), VAT id and registration number. An anonymous user or an unloaded profile gives an empty customer (consumer in the region country).

private getTaxCustomer() : PaymentFormTaxCustomerDTO
Return values
PaymentFormTaxCustomerDTO

hasSelectedItem()

At least one item of any group is selected.

private hasSelectedItem(ArrayHash $values) : bool
Parameters
$values : ArrayHash
Return values
bool

isFinalPriceGate()

Tells whether the gate has final prices; VAT top-up and the final rounding to currency precision are forbidden for it: the data flag `cms_system_payment_gates.final_prices` (checkbox in the gate admin), or a price list in a non-monetary currency (`currencies.monetary = 0`, credits), where VAT is not handled over units. The admin tariff price list keeps the same rule (`Tariff/edit.latte`, `$isFinal`).

private isFinalPriceGate(int|null $paymentGateId) : bool
Parameters
$paymentGateId : int|null
Return values
bool

isNonMonetaryGate()

The price list of the selected gate is in a non-monetary currency (credits).

private isNonMonetaryGate(int|null $paymentGateId) : bool
Parameters
$paymentGateId : int|null
Return values
bool

isSelectionPurchasable()

IMPORTANT: server-side check of the selection. The template forbids unpurchasable items only with the HTML attribute `disabled`, and the server used to accept every offered id: an item without an active price for (region, gate, currency) was left out of the sum (price 0) yet stored as an activation, so after "paying" zero it activated for free (a credit package gave credits without payment).

private isSelectionPurchasable(ArrayHash $values) : bool
Parameters
$values : ArrayHash
Return values
bool —

true when every selected item is offered, is not forFree/paid and has an active price

isTaxResolutionUsable()

Tells whether the engine response is usable: lines without errors (a missing rate or supply kind makes it unusable).

private isTaxResolutionUsable(array<string, mixed> $resolution) : bool
Parameters
$resolution : array<string, mixed>
Return values
bool

isTaxUnavailable()

The engine should have been called for the gate but gave no usable response, so prices are unreliable.

private isTaxUnavailable(ArrayHash $values) : bool
Parameters
$values : ArrayHash
Return values
bool

isVatChargedOn()

Tells whether the engine charges VAT for a response line or share (`treatment.chargeVat` of the line, `chargeVat` of the share).

private isVatChargedOn(array<string, mixed>|null $taxLine) : bool
Parameters
$taxLine : array<string, mixed>|null
Return values
bool

money()

Converts to a money value for `decimal(10,3)`, half-up; a copy of `InvoiceCalculator::money()` (bcmath truncates, hence +0.0005; for negatives -0.0005).

private money(numeric-string $value) : numeric-string
Parameters
$value : numeric-string
Return values
numeric-string

normalizePaymentGateId()

private normalizePaymentGateId(Form $form, ArrayHash $values) : void
Parameters
$form : Form
$values : ArrayHash

num()

Converts an entity or DTO value to a numeric-string safe for bcmath; a copy of `InvoiceCalculator::num()`.

private num(int|float|string $value) : numeric-string
Parameters
$value : int|float|string
Return values
numeric-string

resolveFinalPriceNoteKey()

Returns the note key for a final-prices gate, `price.vatNoteFinal.<script_name>`, but only when the translation exists; otherwise `null` (`{_$vatNoteKey}` on a missing key would print the bare key).

private resolveFinalPriceNoteKey(int|null $paymentGateId) : string|null
Parameters
$paymentGateId : int|null
Return values
string|null

resolveGateCurrency()

Returns the display currency of the selected gate: the currency of the gate prices for this payment region (`payment_gate_region_relations.currency_id`). A credit gate has its price list in a non-monetary currency (`KRD`).

private resolveGateCurrency(int|null $paymentGateId) : object|null

IMPORTANT: the gate list must carry the relation through the include regionRels.currency (the front goes through ApiBridge + hydrator, no lazy loading); the shared PaymentFormPageTrait::preparePaymentGates() supplies it.

Parameters
$paymentGateId : int|null
Return values
object|null

resolveGateId()

Gate id from the form values (0 = not selected).

private resolveGateId(ArrayHash $values) : int
Parameters
$values : ArrayHash
Return values
int

resolveTaxMarker()

Returns the payment marker for which the engine is not called and no invoice arises for the customer, otherwise null: intermediary gate gives `INTERMEDIARY`; a price list in a non-monetary currency gives `CREDIT_REDEMPTION`.

private resolveTaxMarker(int|null $paymentGateId) : string|null
Parameters
$paymentGateId : int|null
Return values
string|null

resolveTaxNote()

Returns the VAT treatment clause (identified person, non-payer, "tax paid by the customer", outside the domestic scope) in the page language and, below it, in Czech; null when none applies (domestic payer, gate marker, engine failed).

private resolveTaxNote(int|null $paymentGateId[, array<string, mixed>|null $resolution = null ]) : string|null
Parameters
$paymentGateId : int|null
$resolution : array<string, mixed>|null = null

null means display (all offered items)

Return values
string|null

resolveVatIdNoticeKey()

Returns the message "VAT id not verified within the last 30 days" when the engine treated a company with an EU VAT id as a consumer (flag `VAT_ID_NOT_VERIFIED`); otherwise null.

private resolveVatIdNoticeKey(int|null $paymentGateId) : string|null
Parameters
$paymentGateId : int|null
Return values
string|null

resolveVatNoteKey()

Returns the key of the VAT note under the price list (translation domain of the component), or `null`: - gate with final prices: its own text `price.vatNoteFinal.<script_name>` (only if it exists), - the engine charges VAT (payer): "Prices include VAT.", - otherwise nothing; identified person, non-payer and reverse charge carry a clause instead ({@see resolveTaxNote()}).

private resolveVatNoteKey(int|null $paymentGateId) : string|null
Parameters
$paymentGateId : int|null
Return values
string|null

roundToPrecision()

IMPORTANT: final rounding of the payable amount to the currency precision, half away from zero, with the same semantics as {@see money()} at `p` places. `p >= MONEY_SCALE` equals {@see money()}. Call it on the unrounded sum, otherwise the amount is rounded twice.

private roundToPrecision(numeric-string $value, int $precision) : numeric-string
Parameters
$value : numeric-string
$precision : int
Return values
numeric-string

translationExists()

Tells whether the translation catalog has a key relative to the component domain. The key is composed like `{_'key'}` in the template (component domain + dot + key); {@see TranslationHelpers::extractMessage()} is the same method that {@see ContributteTranslator::translate()} uses.

private translationExists(string $key) : bool
Parameters
$key : string
Return values
bool

vatMultiplier()

Returns the VAT multiplier `1 + rate/100`; a copy of `InvoiceCalculator::vatMultiplier()`.

private vatMultiplier(numeric-string $vatPercents) : numeric-string
Parameters
$vatPercents : numeric-string
Return values
numeric-string
On this page

Search results