Fluent API Reference

This reference provides a complete technical catalog of all nine domain services accessible via the ium()->accounting() gateway.

1. Account Service: accounts()

Accessed via ium()->accounting()->accounts()

Methods

create(CreateAccountDto $dto): Account

Creates a new account in the Chart of Accounts. If parentId is provided, the parent account is automatically converted into a non-leaf aggregator (is_leaf = false).

findByCode(string $code): ?Account

Finds an account by its unique alphanumeric accounting code.

find(int|string $id): ?Account

Finds an account by its primary key ID.

tree(): Collection<Account>

Returns the hierarchical tree of accounts with child nodes eager-loaded in $account->children.

getBalance(int|string $accountId, ?int $periodId = null): AccountBalanceDto

Calculates running debit, credit, and net balance figures in both minor units and formatted decimal strings.

2. Journal Entry Service: journalEntries()

Accessed via ium()->accounting()->journalEntries()

Methods

createDraft(CreateJournalEntryDto $dto): JournalEntry

Validates zero-sum parity down to integer minor units, verifies leaf accounts, checks open fiscal periods, and persists the draft.

submit(int|string $entryId, int|string $actorId): JournalEntry

Transitions voucher status from DRAFT to SUBMITTED (pending_approval).

approve(int|string $entryId, int|string $approverId): JournalEntry

Approves the voucher. Enforces Maker-Checker segregation when strict governance is enabled.

post(int|string $entryId, int|string $actorId): JournalEntry

Executes posting to the General Ledger. Writes GeneralLedgerPosting rows and locks the voucher permanently against mutation.

reverse(int|string $entryId, int|string $actorId, string $reason): JournalEntry

Generates an equal-and-opposite Storno reversal voucher, marks the original voucher as REVERSED, and posts the reversing entry.

3. General Ledger Service: ledger()

Accessed via ium()->accounting()->ledger()

Methods

generateTrialBalance(?int $periodId = null): array

Returns trial balance summary:

• is_balanced: boolean (true if $\sum \text{Debits} === \sum \text{Credits}$)
• total_debit_minor / total_credit_minor: integers
• total_debit_major / total_credit_major: floats
• lines: array of accounts with balances

generateBalanceSheet(?string $asOfDate = null): array

Compiles Balance Sheet as of a specified date:

• assets, liabilities, equity: categorized account balances
• discrepancy: integer (must be 0)

generateIncomeStatement(int $periodId): array

Calculates Profit & Loss for a fiscal period:

• revenues, expenses: categorized lines
• net_income_minor / net_income_major: net profitability

4. Fiscal Period Service: fiscalPeriods()

Accessed via ium()->accounting()->fiscalPeriods()

Methods

createYear(CreateFiscalYearDto $dto): FiscalYear

Creates a fiscal year and optionally auto-generates 12 monthly periods.

findPeriodForDate(string $date): ?FiscalPeriod

Resolves which fiscal period encompasses a given ISO-8601 transaction date.

setReviewStatus(int $periodId, int|string $actorId): FiscalPeriod

Transitions period into CLOSING_REVIEW soft lock.

closePeriod(int $periodId, int|string $actorId): FiscalPeriod

Applies permanent statutory lock to a period (CLOSED).

5. Year-End Closing Service: closing()

Accessed via ium()->accounting()->closing()

Methods

closeFiscalYear(FiscalYearCloseDto $dto): FiscalYearCloseResultDto

Verifies all prior periods are closed, identifies nominal accounts, generates a zero-sum closing voucher, transfers net income to Retained Earnings, and seals the fiscal year.

6. Currency Service: currencies()

Accessed via ium()->accounting()->currencies()

Methods

create(CreateCurrencyDto $dto): Currency

Registers a new ISO 4217 currency with sub-unit definition.

getBaseCurrency(): Currency

Retrieves the organization’s primary functional reporting currency.

setRate(string $currencyCode, float $rateToBase, string $effectiveDate, string $source = 'manual'): ExchangeRate

Saves an immutable daily exchange rate against base.

convertMinor(int $amountMinor, string $fromCode, string $toCode, ?string $date = null): int

Converts minor units from one currency to another using effective exchange rates.

formatMinor(int $minorUnits, string $currencyCode): string

Formats an integer minor unit balance into a human-readable string (e.g., $ 1,250.00).

7. Cost Center Service: costCenters()

Accessed via ium()->accounting()->costCenters()

Methods

create(CreateCostCenterDto $dto): CostCenter

Registers an analytical dimension (Department, Project, Unit, etc.).

findByCode(string $code): ?CostCenter

Looks up an active cost center by code.

getIncomeStatement(string $costCenterCode, ?int $periodId = null): array

Compiles an Income Statement breakdown specifically filtered by the analytical cost center dimension.

8. Anti-Corruption Layer Service: acl()

Accessed via ium()->accounting()->acl()

Methods

registerMapping(string $eventName, string $debitAccountCode, string $creditAccountCode): EventAccountMapping

Binds an external domain event name to double-entry chart codes.

ingest(AclIngestEventDto $dto): JournalEntry

Ingests an operational domain fact, resolves accounts, verifies zero-sum parity, and creates a posted journal voucher idempotently.

9. Forensic Audit Service: audit()

Accessed via ium()->accounting()->audit()

Methods

forEntry(int|string $entryId): Collection<AuditLog>

Returns the complete append-only forensic event log for a given voucher.