Documentation

TalerOrderLink extends CommonObject
in package

TalerBarr

Class TalerOrderLink

Maps one Taler order (API) to its Dolibarr artefacts (Commande, Facture, Paiement).

Properties

$element : string
$entity : mixed
$fields : mixed
$fk_bank_account_dest : mixed
$fk_commande : mixed
$fk_facture : mixed
$isextrafieldmanaged : mixed
$ismultientitymanaged : mixed
$merchant_status_raw : mixed
$module : string
$picto : string
$rowid : mixed
$table_element : string
$taler_instance : mixed
$taler_order_id : mixed
$tableColumnsCache : array<string, array<string, bool>>

Methods

__construct() : mixed: Constructor
amountStringToFloat() : float|null: Convert an amount string (CUR:value[.fraction]) into float major units.
create() : mixed: Create current object in database (wrapper around CommonObject::createCommon())
delete() : mixed: Delete object from database (wrapper around CommonObject::deleteCommon())
fetch() : int: Fetch object from database using rowid or ref
fetchByInstanceOrderId() : int: Fetch link row using (instance, order_id).
fetchByInvoiceOrOrder() : int: Fetch link row using invoice id and/or commande id.
getNomUrl() : string: Return formatted label or link to the card of this object.
getRefundAmountsSnapshot() : array<string, mixed>: Compute monetary snapshot used for refund eligibility checks.
getRefundPolicy() : array<string, mixed>: Evaluate whether we can still create a Taler refund from this link snapshot.
payloadHasRefundEvidence() : bool: Check whether a status payload contains concrete refund evidence (> 0 or explicit flags/details).
payloadHasWireSettlementEvidence() : bool: Check whether a status payload contains concrete wire settlement evidence.
syncCreditNotePayoutToDolibarr() : int: Persist wallet payout progress of a credit note as native Dolibarr repayments.
toTalerAmountString() : string: Public wrapper to format a decimal amount for Taler API payloads.
update() : mixed: Update object in database (wrapper around CommonObject::updateCommon())
upsertFromDolibarr() : int: Bare-bones upsert when event originates from Dolibarr side (e.g., order creation).
upsertFromTalerOfPayment() : int: Upsert triggered when Taler notifies that the order has been *paid*.
upsertFromTalerOfRefund() : int: Upsert triggered when Taler notifies that a refund was approved.
upsertFromTalerOfWireTransfer() : int: Upsert triggered when Taler notifies that the wire transfer has been executed.
upsertFromTalerOnOrderCreation() : int: Bare-bones upsert when event originates from Taler backend during order creation.
amountToFloat() : float: Convert parsed amount into float (major units, VAT excluded assumption).
amountToRawString() : string: Convert Taler amount-like values into canonical CUR:value[.fraction] strings when possible.
applyRefundMetadata() : void: Persist refund metadata that can come from payment/status/refund payloads.
buildOrderSummary() : string: Build a concise human-readable summary for a Dolibarr customer order.
coalesceString() : string: Helper returning the first non-empty scalar value.
ensureDolibarrOrder() : Commande|null: Ensure a Dolibarr customer order exists and is validated.
ensureInvoice() : Facture|null: Ensure a validated Dolibarr invoice exists for the order link.
ensureInvoiceNoteHasPayLink() : void: Ensure the invoice note contains an up-to-date public payment link.
ensureInvoiceVisibleOnOrder() : void: Make sure the invoice/order linkage is present so the relationship is visible from the UI.
ensurePayment() : Paiement|null: Ensure a Dolibarr payment exists and is linked to the invoice.
ensurePublicNoteHasPayLink() : void: Ensure the original order carries a public note with an accessible Taler link.
ensureUserRightsLoaded() : void: Ensure the user object has rights loaded (required in NOSESSION/CLI contexts).
extractAmount() : array<string, int|string|null>: Parse a Taler amount representation into Dolibarr-friendly parts.
fetchConfigForInstance() : TalerConfig|null: Retrieve Taler configuration row by instance username.
filterFieldsByExistingColumns() : void: Drop field definitions that are not present in the current SQL schema.
findInvoiceLinkedToOrder() : Facture|null: Locate an existing Dolibarr invoice already linked to the provided order.
formatAmountString() : string: Format a decimal amount into Taler amount string (CUR:value[.fraction]).
generateTalerOrderIdForCommande() : string: Generate a Taler order identifier in the format YYYYMMDD-xxxxxx.
hydrateInvoiceSnapshotFromFacture() : void: Synchronize invoice snapshot fields on the link object using the provided invoice.
isProvisionalRef() : bool: Detect Dolibarr provisional references.
linkToCommande() : void: Ensure linked-object relationship is visible from the commande card.
log() : void: Lightweight internal logger utility
logThrowable() : void: Centralised logging helper for unexpected throwables.
looksLikeProvisionalRef() : bool: Detect provisional Dolibarr references like "(PROV 26)" or "PROV26".
normalizeInvoiceReferenceIfProvisional() : bool: Replace a provisional invoice ref with a regular next invoice number.
normalizeRefundDetails() : array<int, array<string, mixed>>: Normalize refund details payload into a list of associative arrays.
normalizeToArray() : array<string, mixed>: Convert mixed (array|object) payload into associative array.
parseBoolish() : bool|null: Parse loosely-typed boolean payload values without PHP string-cast pitfalls.
parseTimestamp() : int|null: Parse various timestamp formats produced by the Taler backend.
resolveClearingAccountId() : int|null: Resolve configured clearing bank account for incoming Taler payments.
resolveCustomerId() : int|null: Resolve default thirdparty/customer identifier.
resolveFinalAccountId() : int|null: Resolve configured final bank account for transfers after clearing.
resolvePaymentModeId() : int|null: Resolve configured payment mode identifier for Taler payments.
sanitizeOrderIdCandidate() : string: Normalize a candidate order identifier to Taler constraints.

$element


        public
            string
    $element
     = 'talerorderlink'

$entity


        public
            mixed
    $entity

$fields


        public
            mixed
    $fields
     = array(
    'rowid' => array('type' => 'integer', 'label' => 'TechnicalID', 'visible' => 0, 'notnull' => 1, 'index' => 1, 'position' => 1),
    'entity' => array('type' => 'integer', 'label' => 'Entity', 'visible' => 0, 'notnull' => 1, 'default' => 1, 'index' => 1, 'position' => 5),
    // Taler identities
    'taler_instance' => array('type' => 'varchar(64)', 'label' => 'TalerInstance', 'visible' => 1, 'enabled' => 1, 'notnull' => 1, 'index' => 1, 'position' => 10),
    'taler_order_id' => array('type' => 'varchar(128)', 'label' => 'TalerOrderId', 'visible' => 1, 'enabled' => 1, 'notnull' => 1, 'index' => 1, 'position' => 11),
    'taler_session_id' => array('type' => 'varchar(128)', 'label' => 'TalerSessionId', 'visible' => 0, 'notnull' => 0, 'position' => 12),
    'taler_pay_uri' => array('type' => 'varchar(255)', 'label' => 'TalerPayURI', 'visible' => 1, 'notnull' => 0, 'position' => 13),
    'taler_status_url' => array('type' => 'varchar(255)', 'label' => 'TalerStatusURL', 'visible' => 1, 'notnull' => 0, 'position' => 14),
    'taler_refund_deadline' => array('type' => 'datetime', 'label' => 'RefundDeadline', 'visible' => 0, 'notnull' => 0, 'position' => 15),
    'taler_pay_deadline' => array('type' => 'datetime', 'label' => 'PayDeadline', 'visible' => 0, 'notnull' => 0, 'position' => 16),
    // Snapshot amount & summary
    'order_summary' => array('type' => 'varchar(255)', 'label' => 'Summary', 'visible' => 1, 'notnull' => 0, 'position' => 20),
    'order_amount_str' => array('type' => 'varchar(64)', 'label' => 'AmountStr', 'visible' => 1, 'enabled' => 1, 'notnull' => 0, 'position' => 21),
    'order_currency' => array('type' => 'varchar(16)', 'label' => 'Currency', 'visible' => 0, 'notnull' => 0, 'position' => 22),
    'order_value' => array('type' => 'integer', 'label' => 'MajorUnits', 'visible' => 0, 'notnull' => 0, 'position' => 23),
    'order_fraction' => array('type' => 'integer', 'label' => 'Fraction1e8', 'visible' => 0, 'notnull' => 0, 'position' => 24),
    'deposit_total_str' => array('type' => 'varchar(64)', 'label' => 'DepositTotalStr', 'visible' => 0, 'notnull' => 0, 'position' => 25),
    // Dolibarr party
    'fk_soc' => array('type' => 'integer:Societe:societe/class/societe.class.php', 'label' => 'Customer', 'visible' => 1, 'notnull' => 0, 'position' => 30, 'index' => 1),
    'order_ref_planned' => array('type' => 'varchar(64)', 'label' => 'OrderRefPlanned', 'visible' => 0, 'notnull' => 0, 'position' => 31),
    // Commande
    'fk_commande' => array('type' => 'integer:Commande:commande/class/commande.class.php', 'label' => 'Commande', 'visible' => 1, 'notnull' => 0, 'position' => 40, 'index' => 1),
    'commande_ref_snap' => array('type' => 'varchar(64)', 'label' => 'CommandeRef', 'visible' => 0, 'notnull' => 0, 'position' => 41),
    'commande_datec' => array('type' => 'datetime', 'label' => 'CommandeDateC', 'visible' => 0, 'notnull' => 0, 'position' => 42),
    'commande_validated_at' => array('type' => 'datetime', 'label' => 'CommandeValidated', 'visible' => 0, 'notnull' => 0, 'position' => 43),
    'intended_payment_code' => array('type' => 'varchar(32)', 'label' => 'IntendedPayCode', 'visible' => 0, 'notnull' => 0, 'position' => 44),
    // Facture
    'fk_facture' => array('type' => 'integer:Facture:compta/facture/class/facture.class.php', 'label' => 'Facture', 'visible' => 1, 'notnull' => 0, 'position' => 50, 'index' => 1),
    'facture_ref_snap' => array('type' => 'varchar(64)', 'label' => 'FactureRef', 'visible' => 0, 'notnull' => 0, 'position' => 51),
    'facture_datef' => array('type' => 'datetime', 'label' => 'FactureDate', 'visible' => 0, 'notnull' => 0, 'position' => 52),
    'fk_cond_reglement' => array('type' => 'integer', 'label' => 'PaymentTerms', 'visible' => 0, 'notnull' => 0, 'position' => 53),
    'facture_validated_at' => array('type' => 'datetime', 'label' => 'FactureValidated', 'visible' => 0, 'notnull' => 0, 'position' => 54),
    // Payment & Bank
    'fk_paiement' => array('type' => 'integer:Paiement:paiement/class/paiement.class.php', 'label' => 'CustomerPayment', 'visible' => 1, 'notnull' => 0, 'position' => 60, 'index' => 1),
    'paiement_datep' => array('type' => 'datetime', 'label' => 'PaymentDate', 'visible' => 0, 'notnull' => 0, 'position' => 61),
    'fk_c_paiement' => array('type' => 'integer', 'label' => 'ModeID', 'visible' => 0, 'notnull' => 0, 'position' => 62),
    'fk_bank' => array('type' => 'integer', 'label' => 'BankLine', 'visible' => 0, 'notnull' => 0, 'position' => 63),
    'fk_bank_account' => array('type' => 'integer', 'label' => 'BankAccount', 'visible' => 0, 'notnull' => 0, 'position' => 64),
    'fk_bank_account_dest' => array('type' => 'integer', 'label' => 'DestBankAccount', 'visible' => 0, 'notnull' => 0, 'position' => 65),
    // Wire settlement
    'taler_wired' => array('type' => 'boolean', 'label' => 'Wired', 'visible' => 1, 'notnull' => 1, 'default' => 0, 'position' => 70),
    'taler_wtid' => array('type' => 'varchar(64)', 'label' => 'WTID', 'visible' => 0, 'notnull' => 0, 'position' => 71),
    'taler_exchange_url' => array('type' => 'varchar(255)', 'label' => 'ExchangeURL', 'visible' => 0, 'notnull' => 0, 'position' => 72),
    'wire_execution_time' => array('type' => 'datetime', 'label' => 'WireExecTime', 'visible' => 0, 'notnull' => 0, 'position' => 73),
    'wire_details_json' => array('type' => 'text', 'label' => 'WireDetails', 'visible' => -1, 'notnull' => 0, 'position' => 74),
    // State machine
    'taler_state' => array('type' => 'integer', 'label' => 'TalerState', 'visible' => 1, 'enabled' => 1, 'notnull' => 0, 'position' => 80),
    'merchant_status_raw' => array('type' => 'varchar(64)', 'label' => 'BackendState', 'visible' => 0, 'enabled' => 1, 'notnull' => 0, 'position' => 86),
    'taler_claimed_at' => array('type' => 'datetime', 'label' => 'ClaimedAt', 'visible' => 0, 'notnull' => 0, 'position' => 81),
    'taler_paid_at' => array('type' => 'datetime', 'label' => 'PaidAt', 'visible' => 0, 'notnull' => 0, 'position' => 82),
    'taler_refunded_total' => array('type' => 'varchar(64)', 'label' => 'RefundedTotal', 'visible' => 0, 'notnull' => 0, 'position' => 83),
    'taler_refund_taken_total' => array('type' => 'varchar(64)', 'label' => 'RefundTakenTotal', 'visible' => 0, 'notnull' => 0, 'position' => 84),
    'taler_refund_pending' => array('type' => 'boolean', 'label' => 'RefundPending', 'visible' => 0, 'notnull' => 1, 'default' => 0, 'position' => 85),
    'taler_refund_last_reason' => array('type' => 'varchar(255)', 'label' => 'RefundLastReason', 'visible' => 0, 'notnull' => 0, 'position' => 86),
    'taler_refund_last_amount' => array('type' => 'varchar(64)', 'label' => 'RefundLastAmount', 'visible' => 0, 'notnull' => 0, 'position' => 87),
    'taler_refund_last_at' => array('type' => 'datetime', 'label' => 'RefundLastAt', 'visible' => 0, 'notnull' => 0, 'position' => 88),
    'taler_refund_details_json' => array('type' => 'text', 'label' => 'RefundDetails', 'visible' => -1, 'notnull' => 0, 'position' => 89),
    'last_status_check_at' => array('type' => 'datetime', 'label' => 'LastStatusChk', 'visible' => 0, 'notnull' => 0, 'position' => 90),
    // Meta
    'idempotency_key' => array('type' => 'varchar(128)', 'label' => 'IdempotencyKey', 'visible' => 0, 'notnull' => 0, 'position' => 91),
    'datec' => array('type' => 'datetime', 'label' => 'DateCreation', 'visible' => -2, 'notnull' => 0, 'position' => 500),
    'tms' => array('type' => 'timestamp', 'label' => 'DateModification', 'visible' => -2, 'notnull' => 1, 'position' => 501),
)

$fk_bank_account_dest


        public
            mixed
    $fk_bank_account_dest

$fk_commande


        public
            mixed
    $fk_commande

$fk_facture


        public
            mixed
    $fk_facture

$isextrafieldmanaged


        public
            mixed
    $isextrafieldmanaged
     = 0

$ismultientitymanaged


        public
            mixed
    $ismultientitymanaged
     = 1

$merchant_status_raw


        public
            mixed
    $merchant_status_raw

$module


        public
            string
    $module
     = 'talerbarr'

$picto


        public
            string
    $picto
     = 'fa-file-invoice-dollar'

$rowid


        public
            mixed
    $rowid

$table_element


        public
            string
    $table_element
     = 'talerbarr_order_link'

$taler_instance


        public
            mixed
    $taler_instance

$taler_order_id


        public
            mixed
    $taler_order_id

$tableColumnsCache


        private
        static    array<string, array<string, bool>>
    $tableColumnsCache
     = array()

__construct()

Constructor


    public
                    __construct(DoliDB $db) : mixed

Parameters

$db : DoliDB: Database connector

amountStringToFloat()

Convert an amount string (CUR:value[.fraction]) into float major units.


    public
            static        amountStringToFloat(string|null $amountString) : float|null

Parameters

$amountString : string|null: Amount string candidate.

Return values

float|null —

Parsed value or null if not parseable.

create()

Create current object in database (wrapper around CommonObject::createCommon())


    public
                    create(User $user[, int $notrigger = 0 ]) : mixed

Parameters

$user : User: Current user performing the action
$notrigger : int = 0: If true, bypass Dolibarr triggers (default 0)

delete()

Delete object from database (wrapper around CommonObject::deleteCommon())


    public
                    delete(User $user[, int $notrigger = 0 ]) : mixed

Parameters

$user : User: Current user performing the action
$notrigger : int = 0: If true, bypass Dolibarr triggers (default 0)

fetch()

Fetch object from database using rowid or ref


    public
                    fetch(int $id[, string|null $ref = null ][, int $noextrafields = 1 ][, int $nolines = 1 ]) : int

Parameters

$id : int: Rowid of the record to fetch
$ref : string|null = null: Optional natural reference
$noextrafields : int = 1: Disable extra fields loading (default 1)
$nolines : int = 1: Disable line objects loading (default 1)

Return values

int —

1 if loaded, 0 if not found, <0 on error

fetchByInstanceOrderId()

Fetch link row using (instance, order_id).


    public
                    fetchByInstanceOrderId(string $instance, string $orderId) : int

Parameters

$instance : string: Instance identifier as configured in TalerConfig::username.
$orderId : string: Taler order identifier.

Return values

int —

0 if found, 0 if not found, <0 on error.

fetchByInvoiceOrOrder()

Fetch link row using invoice id and/or commande id.


    public
                    fetchByInvoiceOrOrder(int $invoiceId[, int $commandeId = 0 ]) : int

Parameters

$invoiceId : int: Invoice identifier (llx_facture.rowid).
$commandeId : int = 0: Commande identifier (llx_commande.rowid).

Return values

int —

0 if found, 0 if not found, <0 on error.

getNomUrl()

Return formatted label or link to the card of this object.


    public
                    getNomUrl([int $withpicto = 0 ][, string $option = '' ][, int $notooltip = 0 ][, string $morecss = '' ][, int|string $save_lastsearch_value = -1 ]) : string

Parameters

$withpicto : int = 0: 0=no picto, 1=include picto, 2=picto only
$option : string = '': Additional options (e.g., 'nolink')
$notooltip : int = 0: Disable tooltips if set to 1
$morecss : string = '': Extra CSS classes for
$save_lastsearch_value : int|string = -1: Manage lastsearch_url feature

Return values

string —

HTML or element with label

getRefundAmountsSnapshot()

Compute monetary snapshot used for refund eligibility checks.


    public
                    getRefundAmountsSnapshot() : array<string, mixed>

Return values

array<string, mixed>

getRefundPolicy()

Evaluate whether we can still create a Taler refund from this link snapshot.


    public
                    getRefundPolicy([int|null $nowTs = null ]) : array<string, mixed>

Parameters

$nowTs : int|null = null: Optional unix timestamp used for comparisons.

Return values

array<string, mixed>

payloadHasRefundEvidence()

Check whether a status payload contains concrete refund evidence (> 0 or explicit flags/details).


    public
            static        payloadHasRefundEvidence(array<string, mixed> $statusData) : bool

refund_amount: CUR:0 is not considered a refund.

Parameters

$statusData : array<string, mixed>: Status payload

Return values

bool

payloadHasWireSettlementEvidence()

Check whether a status payload contains concrete wire settlement evidence.


    public
            static        payloadHasWireSettlementEvidence(array<string, mixed> $statusData) : bool

wired=true alone is not enough because fully-refunded orders may still expose that flag while having no merchant payout wire details.

Parameters

$statusData : array<string, mixed>: Status payload

Return values

bool

syncCreditNotePayoutToDolibarr()

Persist wallet payout progress of a credit note as native Dolibarr repayments.


    public
            static        syncCreditNotePayoutToDolibarr(DoliDB $db, Facture $creditNote, User $user, float $paidOutAmount[, int|null $paidAtTs = null ]) : int

This updates llx_paiement/llx_paiement_facture so the standard credit-note card correctly shows "Already paid back" and "Remaining amount to refund".

Parameters

$db : DoliDB: Database connection.
$creditNote : Facture: Validated credit-note invoice.
$user : User: Current user executing the sync.
$paidOutAmount : float: Total amount already paid out by wallets (positive).
$paidAtTs : int|null = null: Optional payout timestamp.

Return values

int —

1 if a new repayment was created, 0 if nothing to do, -1 on error.

toTalerAmountString()

Public wrapper to format a decimal amount for Taler API payloads.


    public
            static        toTalerAmountString(string $currency, float $amount) : string

Parameters

$currency : string: ISO currency code.
$amount : float: Decimal amount in major units.

Return values

string

update()

Update object in database (wrapper around CommonObject::updateCommon())


    public
                    update(User $user[, int $notrigger = 0 ]) : mixed

Parameters

$user : User: Current user performing the action
$notrigger : int = 0: If true, bypass Dolibarr triggers (default 0)

upsertFromDolibarr()

Bare-bones upsert when event originates from Dolibarr side (e.g., order creation).


    public
            static        upsertFromDolibarr(DoliDB $db, Commande $cmd, User $user) : int

Parameters

$db : DoliDB: DB handler
$cmd : Commande: Dolibarr customer order object
$user : User: Current user

Return values

int —

1=OK, 0=ignored, -1=error (logic TBD)

upsertFromTalerOfPayment()

Upsert triggered when Taler notifies that the order has been *paid*.


    public
            static        upsertFromTalerOfPayment(DoliDB $db, array<string|int, mixed>|object $statusResponse, User $user) : int

Parameters

$db : DoliDB: DB handler
$statusResponse : array<string|int, mixed>|object: Raw MerchantOrderStatusResponse
$user : User: Current user

Return values

int —

1=OK, 0=ignored, -1=error (logic TBD)

upsertFromTalerOfRefund()

Upsert triggered when Taler notifies that a refund was approved.


    public
            static        upsertFromTalerOfRefund(DoliDB $db, array<string|int, mixed>|object $statusResponse, User $user) : int

Parameters

$db : DoliDB: DB handler
$statusResponse : array<string|int, mixed>|object: Raw refund webhook payload
$user : User: Current user

Return values

int —

1=OK, 0=ignored, -1=error

upsertFromTalerOfWireTransfer()

Upsert triggered when Taler notifies that the wire transfer has been executed.


    public
            static        upsertFromTalerOfWireTransfer(DoliDB $db, array<string|int, mixed>|object $statusResponse, User $user) : int

Parameters

$db : DoliDB: DB handler
$statusResponse : array<string|int, mixed>|object: Raw MerchantOrderStatusResponse
$user : User: Current user

Return values

int —

1=OK, 0=ignored, -1=error (logic TBD)

upsertFromTalerOnOrderCreation()

Bare-bones upsert when event originates from Taler backend during order creation.


    public
            static        upsertFromTalerOnOrderCreation(DoliDB $db, array<string|int, mixed>|object $statusResponse, User $user, object|array<string|int, mixed> $contractTerms[, bool|null $allowDolibarrArtefacts = null ]) : int

Parameters

$db : DoliDB: Active Dolibarr DB handler
$statusResponse : array<string|int, mixed>|object: Raw MerchantOrderStatusResponse
$user : User: Current user (for permissions & history)
$contractTerms : object|array<string|int, mixed>: Parsed contract terms payload received from Taler
$allowDolibarrArtefacts : bool|null = null: Whether Dolibarr order/invoice creation is allowed (null follows config)

Return values

int —

1=OK, 0=ignored, -1=error (logic TBD)

amountToFloat()

Convert parsed amount into float (major units, VAT excluded assumption).


    private
            static        amountToFloat(array<string, int|string|null> $parsed) : float

Parameters

$parsed : array<string, int|string|null>: Parsed amount structure.

Return values

float —

Monetary value in major units.

amountToRawString()

Convert Taler amount-like values into canonical CUR:value[.fraction] strings when possible.


    private
            static        amountToRawString(mixed $candidate) : string

Parameters

$candidate : mixed: Amount candidate.

Return values

string

applyRefundMetadata()

Persist refund metadata that can come from payment/status/refund payloads.


    private
            static        applyRefundMetadata(self $link, array<string, mixed> $statusData, DoliDB $db) : void

Parameters

$link : self: Link being updated.
$statusData : array<string, mixed>: Status payload.
$db : DoliDB: DB handler for datetime conversion.

buildOrderSummary()

Build a concise human-readable summary for a Dolibarr customer order.


    private
            static        buildOrderSummary(Commande $cmd) : string

Parameters

$cmd : Commande: Source order instance.

Return values

string —

Summary trimmed to 200 characters.

coalesceString()

Helper returning the first non-empty scalar value.


    private
            static        coalesceString(mixed ...$values) : string

Parameters

$values : mixed: Values to inspect in order.

Return values

string —

First non-empty scalar value (stringified) or empty string.

ensureDolibarrOrder()

Ensure a Dolibarr customer order exists and is validated.


    private
            static        ensureDolibarrOrder(DoliDB $db, User $user, TalerOrderLink $link, array<string|int, mixed> $contractTerms, array<string|int, mixed> $statusData) : Commande|null

Parameters

$db : DoliDB: Database connection.
$user : User: Current user executing the sync.
$link : TalerOrderLink: Order link needing a Dolibarr order.
$contractTerms : array<string|int, mixed>: Contract terms payload from Taler.
$statusData : array<string|int, mixed>: Latest Taler status payload.

Return values

Commande|null —

Created or fetched order, null on failure.

ensureInvoice()

Ensure a validated Dolibarr invoice exists for the order link.


    private
            static        ensureInvoice(DoliDB $db, User $user, TalerOrderLink $link, Commande $commande, array<string|int, mixed> $statusData) : Facture|null

Parameters

$db : DoliDB: Database connection.
$user : User: Current user executing the sync.
$link : TalerOrderLink: Order link referencing the invoice.
$commande : Commande: Source order used to generate invoice lines.
$statusData : array<string|int, mixed>: Latest Taler status payload.

Return values

Facture|null —

Created or fetched invoice, null on failure.

ensureInvoiceNoteHasPayLink()

Ensure the invoice note contains an up-to-date public payment link.


    private
            static        ensureInvoiceNoteHasPayLink(Facture $invoice, string $linkUrl) : void

Parameters

$invoice : Facture: Invoice whose public note should surface the payment URL.
$linkUrl : string: Public status (or payment) URL to surface.

ensureInvoiceVisibleOnOrder()

Make sure the invoice/order linkage is present so the relationship is visible from the UI.


    private
            static        ensureInvoiceVisibleOnOrder(DoliDB $db, Facture $invoice, Commande $order) : void

Parameters

$db : DoliDB: Database connection.
$invoice : Facture: Invoice to link.
$order : Commande: Order to link to.

ensurePayment()

Ensure a Dolibarr payment exists and is linked to the invoice.


    private
            static        ensurePayment(DoliDB $db, User $user, TalerOrderLink $link, Facture $invoice, array<string|int, mixed> $statusData) : Paiement|null

Parameters

$db : DoliDB: Database connection.
$user : User: Current user executing the sync.
$link : TalerOrderLink: Order link referencing the payment.
$invoice : Facture: Invoice to settle.
$statusData : array<string|int, mixed>: Latest Taler status payload.

Return values

Paiement|null —

Created or fetched payment, null on failure.

ensurePublicNoteHasPayLink()

Ensure the original order carries a public note with an accessible Taler link.


    private
            static        ensurePublicNoteHasPayLink(Commande $order, string $linkUrl) : void

Parameters

$order : Commande: Order to update.
$linkUrl : string: Public status (or payment) URL to surface.

ensureUserRightsLoaded()

Ensure the user object has rights loaded (required in NOSESSION/CLI contexts).


    private
            static        ensureUserRightsLoaded(User $user) : void

Parameters

$user : User: Current user.

extractAmount()

Parse a Taler amount representation into Dolibarr-friendly parts.


    private
            static        extractAmount(mixed $amount) : array<string, int|string|null>

Parameters

$amount : mixed: Taler amount structure or string.

Return values

array<string, int|string|null> —

Parsed amount components.

fetchConfigForInstance()

Retrieve Taler configuration row by instance username.


    private
            static        fetchConfigForInstance(DoliDB $db, string $instance) : TalerConfig|null

Parameters

$db : DoliDB: Active database handler.
$instance : string: Taler instance identifier.

Return values

TalerConfig|null —

Loaded configuration or null on failure.

filterFieldsByExistingColumns()

Drop field definitions that are not present in the current SQL schema.


    private
                    filterFieldsByExistingColumns() : void

This keeps list/card pages operational when a module update introduced new columns but the SQL migration was not executed yet.

findInvoiceLinkedToOrder()

Locate an existing Dolibarr invoice already linked to the provided order.


    private
            static        findInvoiceLinkedToOrder(DoliDB $db, Commande $order) : Facture|null

Parameters

$db : DoliDB: Database connector.
$order : Commande: Order whose invoice link we are searching for.

Return values

Facture|null —

First matching invoice (validated preferred), null if none.

formatAmountString()

Format a decimal amount into Taler amount string (CUR:value[.fraction]).


    private
            static        formatAmountString(string $currency, float $amount) : string

Parameters

$currency : string: ISO currency code
$amount : float: Decimal amount (major units)

Return values

string —

Formatted amount string accepted by Taler API

generateTalerOrderIdForCommande()

Generate a Taler order identifier in the format YYYYMMDD-xxxxxx.


    private
            static        generateTalerOrderIdForCommande(Commande $cmd[, int $attempt = 0 ]) : string

The suffix is a 6-digit numeric hash derived from timestamp + business name. A retry attempt may be mixed in to avoid collisions while keeping the format.

Parameters

$cmd : Commande: Source Dolibarr order.
$attempt : int = 0: Collision retry counter (0 for first attempt).

Return values

string

hydrateInvoiceSnapshotFromFacture()

Synchronize invoice snapshot fields on the link object using the provided invoice.


    private
            static        hydrateInvoiceSnapshotFromFacture(DoliDB $db, TalerOrderLink $link, Facture $invoice) : void

Parameters

$db : DoliDB: Database connection for date formatting.
$link : TalerOrderLink: Link being hydrated.
$invoice : Facture: Invoice used as source of truth.

isProvisionalRef()

Detect Dolibarr provisional references.


    private
            static        isProvisionalRef(string $ref) : bool

Parameters

$ref : string: Reference candidate.

Return values

bool

linkToCommande()

Ensure linked-object relationship is visible from the commande card.


    private
            static        linkToCommande(DoliDB $db, TalerOrderLink $link) : void

Parameters

$db : DoliDB: Database connection.
$link : TalerOrderLink: Persisted order link with fk_commande populated.

log()

Lightweight internal logger utility


    private
                    log(string $method[, array<string|int, mixed> $ctx = [] ][, int $lvl = LOG_DEBUG ]) : void

Parameters

$method : string: Name of the calling method (for context)
$ctx : array<string|int, mixed> = []: Arbitrary context information to be serialized to JSON
$lvl : int = LOG_DEBUG: Log level constant, defaults to LOG_DEBUG

logThrowable()

Centralised logging helper for unexpected throwables.


    private
            static        logThrowable(string $context, Throwable $throwable) : void

Parameters

$context : string: Describes the caller for easier troubleshooting.
$throwable : Throwable: Captured exception/error instance.

looksLikeProvisionalRef()

Detect provisional Dolibarr references like "(PROV 26)" or "PROV26".


    private
            static        looksLikeProvisionalRef(string $value) : bool

Parameters

$value : string: Candidate reference.

Return values

bool

normalizeInvoiceReferenceIfProvisional()

Replace a provisional invoice ref with a regular next invoice number.


    private
            static        normalizeInvoiceReferenceIfProvisional(DoliDB $db, Facture $invoice, User $user, TalerOrderLink $link) : bool

Useful to repair legacy rows where payment closed an invoice before validation succeeded.

Parameters

$db : DoliDB: Database handler.
$invoice : Facture: Invoice to normalize.
$user : User: Current sync user.
$link : TalerOrderLink: Related taler link for logging context.

Return values

bool —

True when ref was changed.

normalizeRefundDetails()

Normalize refund details payload into a list of associative arrays.


    private
            static        normalizeRefundDetails(mixed $details) : array<int, array<string, mixed>>

Parameters

$details : mixed: Raw refund details from API payload.

Return values

array<int, array<string, mixed>>

normalizeToArray()

Convert mixed (array|object) payload into associative array.


    private
            static        normalizeToArray(object|array<string|int, mixed>|null $value) : array<string, mixed>

Parameters

$value : object|array<string|int, mixed>|null: Mixed payload to normalize.

Return values

array<string, mixed> —

Normalized associative array.

parseBoolish()

Parse loosely-typed boolean payload values without PHP string-cast pitfalls.


    private
            static        parseBoolish(mixed $value) : bool|null

Parameters

$value : mixed: Raw payload value

Return values

bool|null —

Null when value is absent/unsupported

parseTimestamp()

Parse various timestamp formats produced by the Taler backend.


    private
            static        parseTimestamp(mixed $value) : int|null

Parameters

$value : mixed: Timestamp candidate from Taler payload.

Return values

int|null —

Unix timestamp when parseable, null otherwise.

resolveClearingAccountId()

Resolve configured clearing bank account for incoming Taler payments.


    private
            static        resolveClearingAccountId() : int|null

Return values

int|null —

Bank account identifier or null when not configured.

resolveCustomerId()

Resolve default thirdparty/customer identifier.


    private
            static        resolveCustomerId(TalerOrderLink $link) : int|null

Parameters

$link : TalerOrderLink: Current order link context.

Return values

int|null —

Customer identifier or null if unavailable.

resolveFinalAccountId()

Resolve configured final bank account for transfers after clearing.


    private
            static        resolveFinalAccountId([TalerConfig|null $config = null ]) : int|null

Parameters

$config : TalerConfig|null = null: Optional Taler configuration context.

Return values

int|null —

Bank account identifier or null when not configured.

resolvePaymentModeId()

Resolve configured payment mode identifier for Taler payments.


    private
            static        resolvePaymentModeId() : int|null

Return values

int|null —

Payment mode identifier or null when not configured.

sanitizeOrderIdCandidate()

Normalize a candidate order identifier to Taler constraints.


    private
            static        sanitizeOrderIdCandidate(string $candidate) : string

Parameters

$candidate : string: Raw identifier.

Return values

string —

Sanitized identifier (may be empty).

TalerOrderLink extends CommonObject in package TalerBarr

Tags

Table of Contents

Properties

Methods

Properties

$element

$entity

$fields

$fk_bank_account_dest

$fk_commande

$fk_facture

$isextrafieldmanaged

$ismultientitymanaged

$merchant_status_raw

$module

$picto

$rowid

$table_element

$taler_instance

$taler_order_id

$tableColumnsCache

Methods

__construct()

Parameters

amountStringToFloat()

Parameters

Return values

create()

Parameters

Tags

delete()

Parameters

Tags

fetch()

Parameters

Return values

fetchByInstanceOrderId()

Parameters

Return values

fetchByInvoiceOrOrder()

Parameters

Return values

getNomUrl()

Parameters

Return values

Return values

getRefundPolicy()

Parameters

Return values

payloadHasRefundEvidence()

Parameters

Return values

payloadHasWireSettlementEvidence()

Parameters

Return values

syncCreditNotePayoutToDolibarr()

Parameters

Return values

toTalerAmountString()

Parameters

Return values

update()

Parameters

Tags

upsertFromDolibarr()

Parameters

Return values

upsertFromTalerOfPayment()

Parameters

Return values

upsertFromTalerOfRefund()

Parameters

Return values

upsertFromTalerOfWireTransfer()

Parameters

Return values

upsertFromTalerOnOrderCreation()

Parameters

Return values

TalerOrderLink extends CommonObject
in package

TalerBarr