Download the PHP package syriable/laravel-ledger without Composer

An immutable, append-only, double-entry financial ledger engine for Laravel. Strongly opinionated, minimal core, strict invariants. It records balanced double-entry transactions atomically and idempotently, and reads them back accurately — and it refuses to do anything that would let your books drift. > **Status:** `1.0.0-rc.1` — API frozen for the soak period; behaviour will not change before `1.0.0` unless a critical bug demands it. See [CHANGELOG](CHANGELOG.md) and [UPGRADING](UPGRADING.md). ## Requirements - PHP **8.3** or higher (64-bit) - Laravel **11**, **12**, or **13** - One of: **PostgreSQL 12+**, **MySQL 8+**, **MariaDB 10.4+**, or **SQLite 3.31+** The full CI matrix runs against PostgreSQL 16, MySQL 8, and SQLite on PHP 8.3 and 8.4. ## Installation Install the package via Composer: Publish and run the migrations: Optionally publish the config file: The full config reference (every key, type, and default) lives in [`docs/05-installation-and-quickstart.md`](docs/05-installation-and-quickstart.md#configuration). ## Usage The public surface is three verbs: **open**, **post**, **reverse**. ### Open a ledger and accounts ### Define a Posting A `Posting` is the one and only way to write to the ledger. It is a deterministic domain operation that produces a balanced transaction. ### Post it Posting is idempotent on the `Reference`. Posting the same operation twice returns the original transaction with `wasReplayed = true` — no duplicate write. ### Reverse it A reversal is a new, immutable transaction that inverts the original. A transaction can be reversed at most once, and a reversal cannot itself be reversed — both enforced at the database level. For partial refunds, post a new operation rather than reversing. ### Read balances When you iterate accounts and call `balance()` on each, use the `withBalance` scope to eager-load the projection and avoid an N+1: ### Owner-side ergonomics Apply the `HasAccounts` trait to any model that owns accounts: ### Verify integrity `ledger:verify` checks that every transaction balances, every ledger is zero-sum, and every balance projection matches the entries. It exits non-zero on drift — wire it into your scheduler and your CI. `ledger:simulate` drives a realistic marketplace lifecycle through the real API at volume and verifies the result against an independent shadow ledger — a one-command way to stress-test the package before trusting it with real money. Run it only against a disposable database, and run `php artisan migrate:fresh` before each run to avoid reference collisions with previous runs. See [`docs/09-operations.md`](docs/09-operations.md#rehearsing-a-deployment-with-ledgersimulate). ## Core invariants These are enforced by validators and database constraints. They cannot be relaxed by configuration. - **Append-only** — no financial column on `transactions` or `entries` is ever mutated. - **Always balanced** — `Σ debits == Σ credits` per transaction. - **Single currency per transaction** — FX is two linked postings. - **Entry currency matches account currency.** - **No cross-ledger entries.** - **Amounts are positive integers** — direction is encoded by Debit/Credit. - **Every transaction has a unique idempotency reference.** - **Archived accounts reject new entries** (reversals exempted). - **A transaction can be reversed at most once; reversals cannot be reversed.** - **No soft-deletes** on financial models. - **Money never crosses the float boundary.** See [`docs/03-invariants.md`](docs/03-invariants.md) for the full list and what enforces each one. ## Documentation Full documentation lives in [`docs/`](docs/) — start with the [documentation index](docs/README.md). If you have never worked with a double-entry ledger, read [**The Posting Contract & Direction of Value**](docs/04-the-posting-contract.md) first. **Start here** - [Introduction](docs/01-introduction.md) — why this package exists. - [Concepts](docs/02-concepts.md) — the seven concepts the package is built from. - [Invariants](docs/03-invariants.md) — the financial rules and what enforces each. **Build with the package** - [The Posting Contract](docs/04-the-posting-contract.md) — debit/credit direction and the determinism rules. - [Installation & Quickstart](docs/05-installation-and-quickstart.md) — the full lifecycle in five minutes. - [Postings Cookbook](docs/06-postings-cookbook.md) — a marketplace, worked end to end. - [Reversals vs Refunds](docs/07-reversals-and-refunds.md) — the distinction that causes the most bugs. - [Balances](docs/08-balances.md) — projection vs aggregation, signed balances, overdrafts. **Operate & extend** - [Operations](docs/09-operations.md) — verify, rebuild, Octane, batch posting, drift recovery, legacy imports. - [Extension Points](docs/10-extensions.md) — the five ways to extend the package. - [Events & Exceptions](docs/11-events-and-exceptions.md) — every event and exception, plus listener guidance. - [Anti-features](docs/12-anti-features.md) — what the package will never do. - [Testing](docs/13-testing.md) — how to test a system built on the package. - [FAQ](docs/14-faq.md) — quick answers to common questions. ## Testing The full suite runs against SQLite by default. To exercise the real-database CHECK constraints locally: ## Changelog See [CHANGELOG](CHANGELOG.md). Upgrading from `0.9.x` is covered in [UPGRADING.md](UPGRADING.md) — most installs need only `php artisan migrate`. ## Contributing Please see [CONTRIBUTING](CONTRIBUTING.md) for details — including the explicit list of changes that will be rejected, because this package's invariants are the reason it exists. ## Security Vulnerabilities Please review [our security policy](../../security/policy) on how to report security vulnerabilities. ## Credits - [Syriable](https://github.com/syriable) - [All Contributors](../../contributors) ## License The MIT License (MIT). Please see [License File](LICENSE.md) for more information.