Download the PHP package otim-otim/bookkeeper without Composer

BookKeeper — Accounting for Laravel

BookKeeper is a complete double-entry accounting engine for Laravel. Install it and your application gets:

• Chart of accounts: a hierarchical chart with subtypes, roles and control accounts, plus ready-made templates (general business and Uganda SACCO).
• Immutable journal: balanced entries that can only be corrected by reversal. Entries carry drafts, idempotency keys, branch, source document and creator.
• Fiscal years and periods: periods can be locked. End-of-day, month and year close run with pluggable tasks.
• Subledgers: per-member and per-customer balances on control accounts. They always reconcile to the general ledger.
• Posting templates: map business events (a deposit, a loan disbursement) to journal lines in config.
• Receivables and payables: invoices, credit notes, bills and debit notes. Payments with allocation, withholding tax and realised FX differences. Ageing reports.
• Tax: VAT and withholding tax with effective-dated rates, and a tax report.
• Fixed assets: straight-line and declining-balance depreciation, and disposal.
• Budgets: budget versus actual.
• Teller tills and vaults: cash sessions with overage and shortage posting.
• Bank and mobile-money reconciliation.
• Year-end: surplus appropriation, and dividends on time-weighted balances.
• Reports: trial balance, balance sheet, income statement, cash flow, changes in equity, general ledger, subledger statements and prudential ratios.
• Exact money: amounts are integer minor units with exact decimal arithmetic. Floats are never used for money.
• Any currency, any country:
  • Every ISO 4217 currency is built in, and each set of books has its own locked base currency.
  • Foreign-currency accounts report balances in their own currency.
  • Month-end revaluation, pluggable exchange-rate sources, locale-aware formatting and cash rounding.
  • Chart templates for Uganda, Kenya and Tanzania SACCOs and for IFRS, in English and Swahili.
• Typed API: every write operation accepts a readonly data transfer object (DTO) or the equivalent array.

Requires PHP 8.4+ and Laravel 12 or 13. Works on SQLite, MySQL and PostgreSQL.

Contents

1. Installation
2. Concepts
3. Double-entry bookkeeping
4. Money
5. Currencies and countries
6. Data transfer objects
7. Chart of accounts
8. Journal entries
9. Posting templates
10. Subledgers
11. Periods and closing
12. Receivables and payables
13. Tax
14. Fixed assets
15. Budgets
16. Teller tills
17. Bank and mobile-money reconciliation
18. Surplus appropriation and dividends
19. Reports
20. Events
21. Configuration reference
22. Roles the package uses
23. Database tables
24. Exceptions
25. Multi-tenant applications
26. Using BookKeeper in Suluhu
27. Testing your application
28. Architecture
29. Development with Docker
30. Upgrading from 1.x

Installation

bookkeeper:install imports a chart of accounts and opens the current fiscal year. Run php artisan bookkeeper:install --list to see the available templates.

The base currency is chosen once per set of books, using --currency, the chart's currency, or BOOKKEEPER_CURRENCY. It is locked when the first entry posts. See Currencies and countries.

Concepts

Double-entry bookkeeping

Double entry is the foundation everything else builds on. Invoices, payments, depreciation, tills, dividends and year-end close all post through the same ledger, so every one of them obeys these rules.

Every entry balances. A journal entry has two or more lines. Each line debits or credits one account, and total debits must equal total credits exactly. The check uses integer minor units, so rounding can never let an unbalanced entry through. An unbalanced entry throws UnbalancedEntryException, and nothing is saved.

Balances follow each account type's normal side:

Contra accounts, such as accumulated depreciation and loan-loss provision, carry the opposite balance. They show as negative within their section, so the section totals net off correctly.

The books always agree with themselves. Because every entry balances, the ledger as a whole stays in balance:

• The trial balance always has equal debit and credit totals.
• The balance sheet always satisfies assets = liabilities + equity. Profit not yet closed is shown as current earnings.
• Every subledger (each member's savings, each customer's receivable) sums to its control account.

History is permanent. A posted entry, including its lines, cannot be edited or deleted. A mistake is corrected by BookKeeper::reverse(), which posts a mirror-image entry and links the two. Both stay visible in the ledger, giving a complete audit trail. Entries carry a gap-free number, the user who posted them, the branch and the source business record.

One posting, one transaction. An entry and everything recorded with it (document, payment, allocation, till session) are written in a single database transaction. They are posted together or not at all. An idempotency key makes a retried request return the original entry instead of posting twice.

Money

OtimOtim\BookKeeper\Support\Money holds an amount as an integer number of minor units (cents, or whole shillings for UGX), with exact arithmetic from brick/math.

Raw amounts with more decimals than the currency allows (Money::of('10.005', 'USD')) throw InvalidAmountException. Unknown currency codes throw InvalidCurrencyException. Precision comes from ISO 4217: UGX has 0 decimals, USD and KES have 2, KWD has 3.

Currencies and countries

BookKeeper works in any currency and any country. Nothing is hard-coded to one.

Base currency per set of books. The books' base currency is stored in the database, not taken from config at run time:

• It is set by bookkeeper:install --currency=KES, by BookKeeper::settings()->setBaseCurrency('KES'), or on the first posting, from BOOKKEEPER_CURRENCY.
• After the first posting it can't change. Every stored amount is in that currency, so a later config change can never reinterpret your books.
• In a multi-tenant app, each tenant's books carry their own base currency.

Every ISO 4217 currency is built in, with its correct minor units. Override one, or add a custom unit, in config:

Currency::all(), Currency::precision('KWD'), Currency::name('TZS') and Currency::cashIncrement('CHF') expose the data.

Foreign-currency accounts. Give an account a currency (['currency' => 'USD']) and every line on it must be in that currency. Its balance is reported both ways:

The general ledger and trial balance add currency_balance columns for these accounts. Bank reconciliation of a foreign account works entirely in that account's currency.

Exchange rates. Rates are stored as base units per 1 foreign unit, by date. Lookups use the latest rate on or before the date.

To fetch rates automatically, set exchange_rates.provider and schedule bookkeeper:rates. Two providers are bundled:

To add a source, such as a central bank's feed, implement Contracts\ExchangeRateProvider:

Realised and unrealised exchange differences:

• Realised. Settling a foreign invoice or bill at a different rate posts the difference to fx_gain_loss.
• Unrealised (IAS 21). At month end, closeMonth() restates foreign-currency monetary balances at the closing rate: bank, receivables per customer, payables per vendor, and borrowings.
  • It posts the difference to fx_gain_loss and reverses it the next day.
  • Non-monetary items, such as fixed assets, inventory and prepayments, keep their historical rate.
  • Run it directly with BookKeeper::revaluation()->revalue('2026-03-31'), or preview it with calculate().

Cash rounding. For currencies whose smallest coin is larger than one minor unit (CHF 0.05, UGX 50, SEK 1, ...), document totals can round to the coin. Set 'cash_rounding' => true per document, or documents.cash_rounding globally. The difference posts to the cash_rounding role.

Formatting. Money::format($locale) uses PHP's intl extension, with the locale taken from bookkeeper.locale or the app locale:

• $1,234.50 in en_US
• 1.234,50 € in de_DE
• USh 50,000 in en_UG

Without intl, it falls back to UGX 50,000.

On Alpine images, install icu-data-full. The default ICU data only covers English.

Country chart templates.

Template names can be translations ('name' => ['en' => 'Cash', 'sw' => 'Fedha taslimu']). --locale picks the stored name, and Account::localizedName('sw') returns any other. The Swahili names are a first draft and should be reviewed by a native speaker before production use.

Tax rates, fiscal year start and numbering are all configuration, so any country's rules can be expressed without code changes.

Data transfer objects

Every write operation is described by a readonly DTO in OtimOtim\BookKeeper\Data. Services accept the DTO, or the equivalent snake_case array shown elsewhere in this README, which is converted with Dto::fromArray() at the boundary. Inside, services only work with typed, validated values.

DTOs validate when they are constructed. For example, a subtype that doesn't match its type, a document without lines, or an unknown appropriation base all throw immediately.

Chart of accounts

• Group accounts (is_group) organise the tree and cannot be posted to. An account becomes a group when it gets a child, provided it has no postings.
• Subtypes drive statement classification: current or non-current, liquid, cash-flow category, and contra accounts.
• Tags are free-form labels for regulatory ratios, such as liquid, core_capital and non_earning.
• System accounts come from templates and cannot be deleted. An account with postings can only be deactivated.

Account types and subtypes. The type decides the normal balance and the statement. The subtype refines it:

† Contra account. Cash, bank and mobile money count as cash in the cash flow statement. Investments and fixed assets are investing activities. Borrowings, share capital, dividends payable and drawings are financing. Everything else is operating. Override this per account with cash_flow_category.

Templates are PHP arrays in resources/charts. See the bundled templates under Currencies and countries. Publish them with --tag=bookkeeper-charts, or drop your own into resources/bookkeeper/charts. A template may set a currency, and its account names may be translations.

Journal entries

The v1 line format, ['account' => '1000', 'type' => 'debit', 'amount' => 100], still works.

The rules enforced on every entry:

• Balance. Debits must equal credits, compared exactly.
• Postable accounts. Lines can only go to accounts that are active and not groups.
• Subledgers. Lines on control accounts must name a party.
• Open periods. The entry date must fall in an open period.
• Immutability. Posted entries and their lines cannot be updated or deleted; doing so throws ImmutableRecordException. The only exception is the reversal link.

Posting templates

Templates describe a business event once. Application code then posts it by name.

Each line takes three kinds of value:

• Accounts: a role, #code for an account code, or :key for an account passed in the context.
• Amounts: keys from the amounts array, combined with + and -.
• Subledger: a context key holding the party model.

Lines that add up to zero are skipped. You can also define templates at runtime with BookKeeper::templates()->define().

Subledgers

Periods and closing

The first posting into a date creates its fiscal year and twelve monthly periods automatically. The year starts in the month set by fiscal_year.start_month; set auto_create to false to turn this off.

Each close runs only once per date. Plug in your own end-of-day, month and year work, such as interest accrual, penalties or loan-loss provisioning:

Schedule the artisan commands:

Receivables and payables

• Posting. An invoice debits the receivable control account, with the customer as the subledger party, and credits revenue and output tax. Bills mirror this.
• Withholding tax is deducted from the cash that moves.
• Foreign-currency documents settle at the payment rate. The difference goes to the fx_gain_loss role.

Tax

A purchase rate without an account is not recoverable, so its tax is added to the cost.

Fixed assets

Budgets

Teller tills

Bank and mobile-money reconciliation

Surplus appropriation and dividends

Appropriation is idempotent per fiscal year. Rules can also live in config('bookkeeper.appropriation').

Reports

Every report returns arrays of Money values, ready for response()->json().

Balances use aggregate SQL. Daily snapshots, taken at end of day, keep balance queries fast as history grows, and a back-dated posting invalidates the snapshots it affects.

Events

These events are dispatched after the database transaction commits:

• EntryPosted, EntryReversed
• PeriodClosed, PeriodReopened, FiscalYearClosed, FiscalYearReopened, DayClosed
• DocumentIssued, DocumentVoided, PaymentRecorded, PaymentVoided
• TillSessionClosed, BankStatementReconciled
• AssetsDepreciated, SurplusAppropriated, DividendsPaid

They are all in the OtimOtim\BookKeeper\Events namespace. For example, listen to EntryPosted to flag cash transactions above a reporting threshold.

Configuration reference

Publish the file with php artisan vendor:publish --tag=bookkeeper-config.

Roles the package uses

Some features post to accounts by role. Both bundled charts assign all of them. For a custom chart, give these roles to accounts before using the features that need them:

Database tables

Each table has an Eloquent model in OtimOtim\BookKeeper\Models (Account, JournalEntry, JournalLine, FiscalYear, Period, Document, Payment, ...). Use them freely for reads. For writes, go through the services so the rules are enforced.

Exceptions

Every exception extends OtimOtim\BookKeeper\Exceptions\BookKeeperException.

Multi-tenant applications

BookKeeper's tables carry no tenant column, so each tenant needs its own database or schema. This is the stancl/tenancy model.

The services are stateless, so they work across tenant switches in queue workers and Octane.

Using BookKeeper in Suluhu

Suluhu, the SACCO platform, keeps each SACCO's books in its own PostgreSQL schema. Set it up as follows:

1. Install. Add the package from its VCS repository, publish the tenant migrations, and set BOOKKEEPER_RUN_MIGRATIONS=false and BOOKKEEPER_CURRENCY=UGX.
2. Seed the chart. In the tenant seeder, call BookKeeper::chart()->import('sacco-ug') and BookKeeper::periods()->createFiscalYear(now()->year). The SACCO financial year runs January to December, the default.
3. Fix the accounting service. Rebuild AccountingService on posting templates. Loan approval is not a ledger event, so drop it. Disbursement, repayment, fees, penalties, interest accrual, provisions and write-offs each become a template in config/bookkeeper.php.
4. Post through templates. Savings, shares and loans call BookKeeper::post() inside their own DB transaction, passing the member's account or loan as the subledger party and the request's idempotency key. Member balances then become BookKeeper::subledgers()->balance(), not stored counters.
5. Tellers. Use BookKeeper::tills() for teller sessions, and call assertOpen() before cash postings.
6. Close tasks. Daily interest accrual, arrears ageing and penalties are CloseTasks registered under close.day. Month-end provisioning goes under close.month.
7. Reconciliation. BookKeeper::subledgers()->reconcile('@member_savings') (and the same for loans and shares) is the subledger-versus-control check.
8. Year end. At year end, run closeYear. After the AGM, run appropriation()->appropriate(), then dividends()->calculate() and pay().
9. UMRA ratios. Build these from balanceByTag('liquid'), balanceByTag('short_term'), balanceByTag('core_capital') and balanceSheet()['totals'].

Testing your application

BookKeeper's tables are created by its migrations, so RefreshDatabase works without extra setup. A typical test seeds a chart and asserts on balances:

Freeze the clock (Carbon::setTestNow()) when you assert on dates or periods.

Architecture

BookKeeper is organised around SOLID principles so it can be extended without being edited:

• Single responsibility. Each service owns one area. For example, LedgerService records entries, LineNormalizer validates and converts lines, SettlementService handles allocations and settlement, RevaluationService handles exchange revaluation, and BalanceService aggregates balances. BookKeeperManager, behind the facade, only delegates.
• Open/closed. Behaviour is extended through configuration and contracts, not by changing the package:
  • posting templates, chart templates and role overrides;
  • CloseTask for end-of-day, month and year work;
  • ExchangeRateProvider for rate sources.
• Liskov substitution / interface segregation. The contracts are small, with one method each, so any implementation can stand in.
• Dependency inversion. Services receive their collaborators through the container, and are registered as singletons in BookKeeperServiceProvider::SERVICES. Bind your own subclass to replace one, for example $this->app->singleton(TaxService::class, MyTaxService::class).
• DRY. Shared rules live in one place:
  • AccountReference parses role, #code and :context references.
  • Morph builds polymorphic columns.
  • LineData::converted() and LineData::signed() build foreign-currency and sign-dependent lines.
  • Account::balanceIn() turns aggregated totals into a balance.
  • Currency data lives only in Currency/Iso4217.

Development with Docker

The image is PHP 8.5 CLI with Composer, PCOV and the SQLite, MySQL and PostgreSQL drivers.

Without Docker, run composer install and then vendor/bin/pest.

Upgrading from 1.x

Version 2 has a new schema and returns Money instead of floats. See UPGRADE.md.

License

MIT