Journal Vouchers & General Ledger

The General Ledger represents the financial truth of an organization. In Obelawium Accounting, all ledger mutations take the form of balanced Journal Vouchers managed through ium()->accounting()->journalEntries() and reported through ium()->accounting()->ledger().

1. The Voucher Lifecycle

A journal voucher advances through an explicit state machine:

stateDiagram-v2
    [*] --> DRAFT: createDraft()
    DRAFT --> SUBMITTED: submit(actorId)
    SUBMITTED --> APPROVED: approve(approverId)
    SUBMITTED --> REJECTED: reject(approverId, reason)
    REJECTED --> DRAFT: revise()
    APPROVED --> POSTED: post(actorId)
    POSTED --> REVERSED: reverse(actorId, reason)
    REVERSED --> [*]

2. Drafting a Balanced Journal Voucher

Vouchers can be defined using minor units (integers) or major units (decimals) via CreateJournalEntryDto.

Using Decimal Major Units (fromMajor)

use Obelaw\Ium\Accounting\Data\CreateJournalEntryDto;
use Obelaw\Ium\Accounting\Enums\JournalEntryType;

$dto = CreateJournalEntryDto::fromMajor([
    'entry_date'    => '2026-03-31',
    'entry_type'    => JournalEntryType::Standard,
    'currency_code' => 'USD',
    'memo'          => 'Office Equipment Purchase via Bank Wire',
    'lines' => [
        [
            'account_code'     => '1510', // Office Equipment (Leaf Asset)
            'side'             => 'debit',
            'amount'           => 4250.00,
            'cost_center_code' => 'CC-OPS',
            'memo'             => 'MacBook Pro workstations',
        ],
        [
            'account_code'     => '1111', // Bank Operating (Leaf Asset)
            'side'             => 'credit',
            'amount'           => 4250.00,
            'memo'             => 'Wire Transfer #9021',
        ],
    ],
]);

// Persists the voucher with status = DRAFT
$voucher = ium()->accounting()->journalEntries()->createDraft($dto);

The Zero-Sum Check

When saving or submitting, the system asserts:

$$\sum \text{Debits (minor)} = \sum \text{Credits (minor)}$$

If debits and credits do not match to the exact integer minor unit, the method halts immediately with an UnbalancedJournalEntryException.

3. Maker-Checker Segregation of Duties

To protect organizations from unilateral or fraudulent ledger disbursements, ium-accounting features built-in Maker-Checker governance:

// Step 1: Preparer / Accountant submits the draft
ium()->accounting()->journalEntries()->submit($voucher->id, $preparerId);

// Step 2: Financial Controller / Auditor reviews and approves
// If $controllerId === $voucher->creator_id, throws MakerCheckerViolationException!
ium()->accounting()->journalEntries()->approve($voucher->id, $controllerId);

// Step 3: Posting to the General Ledger
$postedVoucher = ium()->accounting()->journalEntries()->post($voucher->id, $controllerId);

Strict Governance Setting: Set config('ium.accounting.maker_checker.strict') to false only in local development or single-user environments.

4. General Ledger Postings & Immutability

When a voucher is posted:

1. JournalEntry status transitions permanently to POSTED.
2. Individual GeneralLedgerPosting rows are written for each line item.
3. Amounts are converted into the functional base currency: $$amount_functional = \text{round}(amount \times exchange_rate)$$
4. Eloquent model hooks lock the voucher. Any subsequent in-place SQL UPDATE or DELETE throws an ImmutableJournalEntryException.

5. Correcting Errors: The Storno Reversal Pattern

GAAP and IFRS standards forbid deleting or modifying posted financial records. Corrections must always generate an equal-and-opposite Storno Reversal:

$reversalVoucher = ium()->accounting()->journalEntries()->reverse(
    entryId: $postedVoucher->id,
    actorId: $controllerId,
    reason: 'Incorrect asset account selected on original purchase wire'
);

What Happens During a Storno Reversal?

1. The original entry status becomes REVERSED.
2. A new journal entry is created with status POSTED and entry_type = JournalEntryType::Reversal.
3. The new entry contains identical accounts and amounts, but with inverted sides: original debits become credits, and original credits become debits.
4. The new entry links back via reversed_entry_id = $original->id.
5. The forensic audit log records both actors, timestamps, and justification.

6. Real-Time Financial Statements

Query the General Ledger via ium()->accounting()->ledger():

Trial Balance

$tb = ium()->accounting()->ledger()->generateTrialBalance($periodId = null);

// Verification check
if ($tb['is_balanced'] === true) {
    echo "Trial balance verified: Debits = {$tb['total_debit_major']}, Credits = {$tb['total_credit_major']}\n";
}

Balance Sheet

$balanceSheet = ium()->accounting()->ledger()->generateBalanceSheet($asOfDate = '2026-03-31');

dump($balanceSheet['assets']);
dump($balanceSheet['liabilities']);
dump($balanceSheet['equity']);
dump($balanceSheet['discrepancy']); // Guaranteed 0

Income Statement (Profit & Loss)

$pnl = ium()->accounting()->ledger()->generateIncomeStatement($periodId);

echo "Revenues: {$pnl['total_revenue_major']}\n";
echo "Expenses: {$pnl['total_expense_major']}\n";
echo "Net Income: {$pnl['net_income_major']}\n";