Installation & Setup

v0.1.0

Composer installation, service provider registration, database migrations, configuration, and turnkey demo seeding.

Installation & Setup

This guide walks you through installing, configuring, and initializing the Obelawium Accounting module (obelaw/ium-accounting) in your Laravel application.

Prerequisites

PHP: 8.2 or higher
Laravel Framework: 11.0, 12.0, or 13.0
Database: MySQL 8.0+, PostgreSQL 14+, or SQLite 3.38+
Obelawium Framework: obelaw/ium

1. Installation via Composer

Install the accounting package into your Laravel application:

composer require obelaw/ium-accounting

GitHub Repository Reference

The canonical source repository for the package is hosted at:

https://github.com/obelaw/ium-accounting

2. Service Provider Registration

In standard Laravel installations with package auto-discovery, the service provider is registered automatically:

Obelaw\Ium\Accounting\Providers\ObelawAccountingServiceProvider::class

If you manage providers manually in bootstrap/providers.php or config/app.php, ensure it is included in your providers list.

3. Publishing the Configuration

Publish the accounting configuration file:

php artisan vendor:publish --tag="ium-accounting-config"

This creates config/ium/accounting.php:

return [
    /*
    |--------------------------------------------------------------------------
    | Database Connection
    |--------------------------------------------------------------------------
    |
    | Define the database connection used by accounting models. Defaults to
    | your application's default database connection.
    |
    */
    'connection' => env('IUM_ACCOUNTING_DB_CONNECTION', null),

    /*
    |--------------------------------------------------------------------------
    | Table Prefix
    |--------------------------------------------------------------------------
    |
    | All accounting domain tables are isolated with this prefix.
    |
    */
    'table_prefix' => 'ium_accounting_',

    /*
    |--------------------------------------------------------------------------
    | Base Currency
    |--------------------------------------------------------------------------
    |
    | Default functional reporting currency for the General Ledger.
    |
    */
    'base_currency' => env('IUM_ACCOUNTING_BASE_CURRENCY', 'USD'),

    /*
    |--------------------------------------------------------------------------
    | Maker-Checker Governance
    |--------------------------------------------------------------------------
    |
    | When strict mode is enabled, the author of a journal entry cannot
    | approve that entry, enforcing four-eyes segregation of duties.
    |
    */
    'maker_checker' => [
        'strict' => env('IUM_ACCOUNTING_MAKER_CHECKER_STRICT', true),
    ],

    /*
    |--------------------------------------------------------------------------
    | Auto Numbering & Voucher Sequences
    |--------------------------------------------------------------------------
    */
    'numbering' => [
        'prefix' => 'JV-',
        'pad_length' => 6,
    ],
];

4. Running Migrations

All accounting tables use the ium_accounting_ table prefix to prevent collisions with existing application tables.

Run the migrations:

php artisan migrate

Generated Tables

Table Name	Description
`ium_accounting_accounts`	Chart of Accounts hierarchy, codes, classifications, and leaf status.
`ium_accounting_journal_entries`	Journal entry headers, statuses (`DRAFT`, `SUBMITTED`, `POSTED`, `REVERSED`), memos, dates.
`ium_accounting_journal_entry_lines`	Debit and credit line items denominated in integer minor units.
`ium_accounting_gl_postings`	Immutable General Ledger postings denominated in functional base currency.
`ium_accounting_fiscal_years`	Fiscal years, start/end dates, and closed flags.
`ium_accounting_fiscal_periods`	Fiscal periods (monthly/quarterly) and status locks (`OPEN`, `CLOSING_REVIEW`, `CLOSED`).
`ium_accounting_cost_centers`	Analytical dimensions (Cost Centers, Departments, Projects, Units).
`ium_accounting_currencies`	ISO 4217 currency registry and sub-unit decimal definitions.
`ium_accounting_exchange_rates`	Historical FX rate snapshots against the base functional currency.
`ium_accounting_event_account_mappings`	Anti-Corruption Layer (ACL) mappings linking domain event names to debit/credit account codes.
`ium_accounting_audit_logs`	Append-only forensic accounting audit trail.

5. Turnkey Demo Seeding

To quickly stand up a fully populated, balanced, multi-currency ledger with an established Chart of Accounts, active fiscal periods, and sample journal postings, run the built-in demo seeder:

php artisan ium:accounting:demo-seed

Available Seeder Flags

# Wipe existing demo data and reseed freshly
php artisan ium:accounting:demo-seed --fresh

# Force execution in production environments
php artisan ium:accounting:demo-seed --force

6. Verifying the Gateway

Verify that the fluent gateway is reachable from php artisan tinker:

// Check the gateway version and registered services
$baseCurrency = ium()->accounting()->currencies()->getBaseCurrency();
dump($baseCurrency->code); // 'USD'

// Inspect the root Chart of Accounts
$accounts = ium()->accounting()->accounts()->tree();
dump($accounts->count());

AI Agent Integration Skill

If you are developing with Google Antigravity, Claude Code, or Cursor AI, install the dedicated development skill:

Repository: https://github.com/obelaw/skill-ium-accounting-developmint

This skill provides AI agents with instant contextual awareness of the 8 domain invariants, DTO contracts, and service orchestration patterns.