Package API Reference

A method-by-method reference for everything the package exposes: the LaravelAccounting facade, its seven underlying services, the Eloquent models, the Postable trait/template system, the DTOs that move data between them, the enums, events, and exceptions.

For the full catalog of posting templates and which real-world transactions they cover, see Available Accounting Templates. This document covers the API surface those templates sit on top of.

How the pieces fit together

Your Model (implements PostableModel, uses Postable trait)
    │
    │  ->post()
    ▼
getTemplate()  →  AccountingTemplate::make($model)  →  VoucherData
                                                            │
                                                            │  JournalService::createDraft()
                                                            ▼
                                                      JournalEntry (draft, unposted)
                                                            │
                                                            │  JournalService::post()
                                                            ▼
                                                      JournalEntry (posted, immutable)

Everything in the package funnels through JournalService::createDraft() + post() — the named PostingService shortcuts, LaravelAccounting::postModel()/postRaw(), and $model->post() are all thin wrappers around that same pair of calls. A posted JournalEntry can only be reversed or voided afterward; JournalEntryObserver blocks any other update at the database level, so there is no path that bypasses this.

The Facade

use RingleSoft\LaravelAccounting\Facades\LaravelAccounting;

All eight sub-services are resolved fresh from the container on each call (app(XService::class)) rather than cached on the facade instance, so they pick up any container bindings/mocks a test has swapped in.

---

Services

Accounts — AccountService

Balances — BalanceService

Journals — JournalService

Every post()/reverse()/void() call locks the row and re-checks its state under that lock, not the possibly-stale entry the caller passed in — this is what makes two concurrent calls on the same entry safe instead of racing.

Posting — PostingService

Named shortcuts for the standard transaction types. Each one resolves a registered template (see Templates below) and runs it through createDraft() + post() in a single call — equivalent to calling $model->postWithTemplate($template) with that template already selected for you.

LaravelAccounting::posting()->cashSale($invoice);
// same as:
$invoice->postWithTemplate(TemplateRegistry::make('sale.cash'));

Every method's signature is (PostableModel $model, string|int|null $userId = null): JournalEntry except bankTransfer (extra $fromAccountId/$toAccountId params, unused by the method body — kept for call-site clarity) and inventoryPurchase (extra bool $onAccount). All of them can throw AccountNotFoundException, InvalidVoucherException, JournalNotBalancedException, ParentAccountPostingException (from template resolution), and PeriodClosedException/DuplicatePostingException (from posting).

Periods — PeriodService

Closing — ClosingService

Posts the standard period-end closing entries: Revenue → Income Summary, Expenses → Income Summary, Income Summary's net result → Retained Earnings, Dividends Declared → Retained Earnings. This is what lets the Balance Sheet actually balance at year-end — without it, Revenue/Expense balances just keep accumulating forever.

Every commit*() method posts through the normal JournalService::createDraft() + post() path — nothing bypasses it. Every preview*() method is a pure read that builds the exact VoucherData that would be posted, without writing anything. Each step reads the ledger's actual current state, not a cached calculation, so calling them in any order, any number of times, is safe — a step with nothing left to close just returns null.

Reports — ReportService

LaravelAccounting::reports()->generate('trial_balance', ['as_of_date' => now()]);
// or the camelCase shortcut (magic __call, resolves to the same generate() call):
LaravelAccounting::reports()->trialBalance(['as_of_date' => now()])->getData();

Every report is a Report subclass (see Models → Report) and every call to generate()/the camelCase shortcuts is cached (report_cache_enabled, TTL report_cache_ttl), keyed per-tenant so two tenants never see each other's cached figures. Other methods:

---

Models

All of them use HasTablePrefix (table name auto-prefixed from laravel_accounting.table_prefix) and MultiTenant (global scope on tenant_id — see Multi-Tenancy). JournalEntry additionally uses HasUuid (switches the primary key to a UUID when use_uuid is enabled).

JournalEntry also exposes convenience instance methods that just delegate to JournalService: isBalanced(), getTotalDebits()/getTotalCredits(), canBePosted()/canBeVoided()/canBeReversed(), and post()/reverse(?string $reason)/void(?string $reason).

Account exposes hierarchy helpers: getFullCode() (dotted ancestor codes, e.g. "1000.1010"), getAncestors()/getDescendants(), isParentOf()/isChildOf()/isDescendantOf().

Both Account and JournalEntry expose a static validationRules(?int $ignoreId = null): array backed by AccountValidator/JournalEntryValidator, for reuse in your own form requests.

The Report base class

Every class in src/Reports/ (BalanceSheet, IncomeStatement, CashFlowStatement, TrialBalance, GeneralLedger, AccountLedger, ChartsOfAccounts) extends this abstract class:

Model-level guardrails (Observers)

These fire regardless of whether you go through a service or call Eloquent directly — they're the backstop that makes "posted entries are immutable" actually true at the data layer, not just a convention the services happen to follow:

• JournalEntryObserver: rejects any update() to a posted entry except the fields reverse()/void() themselves touch (is_voided, voided_at, voided_by_user_id, is_reversed); rejects delete() on a posted entry entirely (reverse or void it instead).
• AccountObserver: rejects delete() on an account with transactions or children; rejects changing account_type_id on an account with transactions; rejects a circular parent_id.
• FiscalPeriodObserver: validates start_date < end_date and a ≤366-day span; rejects overlapping periods within the same fiscal year; rejects any change but is_locked on a locked period; rejects date changes on a closed period; rejects delete() on a closed/locked period or one with journal entries.

---

The Postable trait & PostableModel contract

Turns any Eloquent model into a source of journal entries. Implement the interface, apply the trait, implement getPostableAmount() yourself (it's intentionally not provided — "amount" is domain-specific):

use RingleSoft\LaravelAccounting\Contracts\PostableModel;
use RingleSoft\LaravelAccounting\Traits\Postable;
use RingleSoft\LaravelAccounting\Attributes\DefaultAccountingTemplate;
use RingleSoft\LaravelAccounting\Templates\CreditSaleTemplate;

#[DefaultAccountingTemplate(CreditSaleTemplate::class)]
class Invoice extends Model implements PostableModel
{
    use Postable;

    public function getPostableAmount(): float
    {
        return $this->total;
    }
}

// Option A: default template via the attribute
$invoice = Invoice::create(['total' => 5000]);
$invoice->post();
echo $invoice->journalEntry->transaction_number;

// Option B: explicit template + overridden accounts, bypassing the attribute
use RingleSoft\LaravelAccounting\Templates\CreditSaleTemplate;
use RingleSoft\LaravelAccounting\Enums\AccountPreset;

$invoice->postWithTemplate(new CreditSaleTemplate(cashAccount: AccountPreset::PETTY_CASH));

A model can also implement the optional ResolvesAccountPresets contract (one method, resolveAccountForPreset(AccountPreset $preset): int|string|Account|null) to resolve a preset to a specific account dynamically — e.g. picking a customer-specific receivable account — without hardcoding it into the template. It's consulted after an explicit resolveAccount() override on the template, but before the default preset lookup.

---

Templates — AccountingTemplate & TemplateRegistry

An AccountingTemplate is a reusable debit/credit pattern. TemplateRegistry resolves a short string key (used by PostingService and the '...' keys in the table above) to a template class:

use RingleSoft\LaravelAccounting\Templates\TemplateRegistry;

$template = TemplateRegistry::make('sale.cash');                    // no constructor args
$template = TemplateRegistry::make('sale.cash', [taxRate: 0.16]);    // positional/named constructor args

TemplateRegistry::register('custom.refund', CustomRefundTemplate::class);
TemplateRegistry::templates(); // the full key => class map, ~40 entries

Building a template means implementing configure() (abstract), declaring entries with debit()/credit():

class CashSaleTemplate extends AccountingTemplate
{
    public function __construct(
        protected AccountPreset $cashAccount = AccountPreset::CASH,
        protected AccountPreset $revenueAccount = AccountPreset::SALES_REVENUE,
        protected ?AccountPreset $taxAccount = AccountPreset::SALES_TAX_PAYABLE,
        protected float $taxRate = 0.0
    ) {}

    public function configure(): void
    {
        $this->debit($this->cashAccount)
            ->credit($this->revenueAccount, fn ($amount) => $amount / (1 + $this->taxRate));

        if ($this->taxRate > 0 && $this->taxAccount) {
            $this->credit($this->taxAccount, fn ($amount) => $amount * $this->taxRate / (1 + $this->taxRate));
        }
    }
}

Preset → account resolution order (in make(), per entry): an explicit resolveAccount() override on this template instance → the model's own resolveAccountForPreset() if it implements ResolvesAccountPresets → the default lookup (no children = the account itself; exactly one child = that child; more than one child = ParentAccountPostingException, unless allow_posting_on_parents is enabled).

See Available Accounting Templates for the full ~40-template catalog by category, the accrual-vs-cash account pairing table, and a complete custom-template walkthrough (validation, testing, gotchas).

---

DTOs

VoucherData

The intermediate representation every journal entry is built from — whether it came from a template or you built it by hand.

use RingleSoft\LaravelAccounting\DTOs\VoucherData;

$voucher = VoucherData::make()
    ->describe('Manual adjustment')
    ->on(now())
    ->currency('USD')
    ->debit($expenseAccountId, 150.00, 'Office supplies')
    ->credit($cashAccountId, 150.00, 'Office supplies');

$entry = $voucher->createJournal(); // JournalService::createDraft()

VoucherDataItem

One debit or credit line: type (EntryType), accountId, amount (always positive — sign comes from type, not the number), memo, dimension. Static constructors debit()/credit(). Helpers: isDebit()/isCredit(), getDebitAmount()/getCreditAmount() (one returns the amount, the other 0), toArray(). Validates in its own constructor — throws InvalidArgumentException for a missing account id or an amount ≤ 0.

AccountTemplateEntry

A template's unresolved entry, before the preset becomes a real account id: type, account (an AccountPreset, not yet an id), amount (a Closure(float): float, a fixed float, or null to use the full posted amount unchanged), memo. Static constructors debit()/credit(); getAmount(float $baseAmount): float resolves the closure/value.

BalanceData

A free-standing opening/debits/credits/closing accumulator — not used internally by the services above (which return plain arrays), but available for building your own balance calculations. addDebit()/addCredit(), calculateClosing(string $normalBalance = 'debit'), getNetMovement()/getTotalActivity()/getChange()/getPercentageChange(), toArray()/fromArray().

ClosingEntryPreview / ClosingResult

Returned by ClosingService::preview() / commit() respectively — four nullable VoucherData/JournalEntry fields (one per closing step) plus totalRevenue, totalExpenses, netIncome, dividendsDeclared. Both expose isProfit(): bool and hasNothingToClose()/hasNothingClosed(): bool, plus toArray().

TaxData

account (AccountPreset), rate, optional amount closure override, optional baseAccount, memo. A building block for templates that need a tax line (see CashSaleTemplate's taxRate parameter for the pattern it supports).

---

Enums

TransactionTemplate (src/Enums/TransactionTemplate.php) is a larger taxonomy of ~90 named transaction types mirroring the rows in Financial Transactions. It currently isn't referenced anywhere else in the package — treat it as a reserved vocabulary, not a live dependency of anything above.

---

Events

All fired via Laravel's standard event() — listen for them the usual way (EventServiceProvider, or Event::listen()).

The built-in InvalidateAccountingCaches listener (registered in the service provider) subscribes to the relevant events above and clears the report cache automatically — you don't need to call ReportService::clearCache() yourself after normal posting/closing activity.

---

Exceptions

Every exception the package throws extends the single base class, so catch (LaravelAccountingException $e) catches all of them:

use RingleSoft\LaravelAccounting\Exceptions\LaravelAccountingException;

try {
    $invoice->post();
} catch (LaravelAccountingException $e) {
    // AccountNotFoundException, JournalNotBalancedException, PeriodClosedException, ...
}

A few of these ("Reserved") are defined for API completeness/future use but aren't thrown by any code path yet — don't rely on catching them specifically; catch LaravelAccountingException for forward compatibility instead.

---

Multi-Tenancy

Every model using the MultiTenant trait gets a global scope that filters by the authenticated user's tenant_id (configurable field name via multi_tenancy_field) and auto-fills tenant_id on create from the authenticated user — a caller-supplied tenant_id in mass-assigned data is always overridden by the authenticated user's own tenant, so one tenant's request can never attribute data to another. With no authenticated user (CLI, queue, seeder) and strict_multi_tenancy_check enabled, creating a record with no resolvable tenant_id throws TenantRequiredException; with it disabled (the default), a null tenant_id is allowed and the row becomes visible as "global/shared" to every tenant.

ReportService additionally scopes its cache keys by tenant — not the report queries themselves (those rely entirely on the models' own global scope) — so two tenants requesting the same report type never collide on the same cache entry.

Artisan Commands

Configuration

Published to config/laravel_accounting.php by the installer. The full annotated reference lives in the main README's Configuration section — summarized here for convenience:

table_prefix, multi_tenancy_field, strict_multi_tenancy_check, default_currency_code, transaction_number_prefix, use_uuid, default_fiscal_year_start, fiscal_periods_count, cash_basis (informational only, not enforced), auto_post, balance_cache_enabled, report_cache_enabled, report_cache_ttl, cache_prefix, supported_currencies, account_code_format, allow_posting_on_parents.

See Also

• Available Accounting Templates — the full template catalog, accrual-vs-cash guidance, and how to write your own template
• Financial Transactions — 100+ standard transactions mapped to the template/method that posts each one
• README — installation, quick start, and architecture overview