README

Central transaction hub for all financial entries in the Nexus ERP system.

Purpose

The Nexus\GeneralLedger package is a Layer-1 atomic package that serves as the central transaction hub for all financial entries in the Nexus ERP system. The General Ledger (GL) is the core of any financial system - all journal entries from subledgers (Receivables, Payables, Assets, etc.) must ultimately be posted to the GL to ensure accounting accuracy and generate financial statements.

Key Features

Ledger Master Data Management: Create, update, and manage multiple ledgers per tenant (statutory and management ledgers)
Ledger Account Management: Register and manage accounts within the ledger, integrating with ChartOfAccount
Journal Entry Posting: Post validated journal entries to the general ledger with full audit trail
Account Balance Calculation: Real-time calculation of debit/credit balances as of any date
Trial Balance Generation: Generate comprehensive trial balance reports for all accounts
Multi-Entity Support: Support for multiple entities (tenants) with isolated ledger data
Multi-Currency Support: Handle transactions in multiple currencies with proper conversion
Subledger Integration: Interfaces for AR, AP, and Assets subledgers to post transactions to GL
Fiscal Period Validation: Enforce posting only to open accounting periods
Transaction Reversal: Reverse posted transactions with full audit trail

Installation

composer require azaharizaman/nexus-general-ledger

Requirements

PHP ^8.3
azaharizaman/nexus-common ^1.0
brick/math ^0.12

Usage

Creating a Ledger

use Nexus\GeneralLedger\Services\LedgerService;
use Nexus\GeneralLedger\Enums\LedgerType;

// $ledgerService should be injected via IdGeneratorInterface
$ledger = $ledgerService->createLedger(
    tenantId: 'tenant-123',
    name: 'Statutory Ledger',
    type: LedgerType::STATUTORY,
    currency: 'USD',
    description: 'Main statutory ledger'
);

echo $ledger->id; // generated ID string

Calculating Account Balances

use Nexus\GeneralLedger\Services\TransactionService;

$balance = $transactionService->getAccountBalance(
    $account->id,
    new DateTimeImmutable('2024-01-31')
);

echo $balance->getAmount()->getAmount(); // Account balance as of date
echo $balance->balanceType->value; // debit or credit

Generating Trial Balance

$trialBalance = $trialBalanceService->generateTrialBalance(
    $ledger->id,
    'period-2024-01'
);

echo $trialBalance->totalDebits->getAmount();
echo $trialBalance->totalCredits->getAmount();
echo $trialBalance->isBalanced; // true if debits = credits

foreach ($trialBalance->lines as $line) {
    // Correctly access TrialBalanceLine properties
    $balance = $line->getNetBalance();
    echo $line->accountCode . ': ' . $balance->getAmount();
}

Interfaces

Core Interfaces

Interface	Description
`SubledgerPostingInterface`	Interface for subledgers to post to GL
`IdGeneratorInterface`	Framework-agnostic unique ID generation
`DatabaseTransactionInterface`	Framework-agnostic transaction management

Repository Interfaces (CQRS)

Interface	Description
`LedgerQueryInterface`	Read operations for Ledgers
`LedgerPersistInterface`	Write operations for Ledgers
`LedgerAccountQueryInterface`	Read operations for LedgerAccounts
`LedgerAccountPersistInterface`	Write operations for LedgerAccounts
`TransactionQueryInterface`	Read operations for Transactions
`TransactionPersistInterface`	Write operations for Transactions

Models (Entities)

Entity	Description
`Ledger`	Immutable ledger entity
`LedgerAccount`	Immutable ledger account entity
`Transaction`	Immutable transaction entity
`TrialBalance`	Immutable trial balance report entity
`TrialBalanceLine`	Individual line in a trial balance

Value Objects

Value Object	Description
`AccountBalance`	Represents balance with debit/credit type
`TransactionDetail`	Transaction metadata for posting
`PostingResult`	Result of a posting operation
`SubledgerPostingRequest`	Request from a subledger
`ValidationResult`	Result of a validation check

Exceptions

Exception	Description
`GeneralLedgerException`	Base GL exception
`LedgerNotFoundException`	Ledger not found
`LedgerAlreadyActiveException`	Ledger already active
`LedgerAlreadyClosedException`	Ledger already closed
`LedgerArchivedException`	Ledger is archived
`AccountNotFoundException`	Account not found
`PeriodClosedException`	Posting to closed period
`InvalidPostingException`	Posting validation failed
`TransactionAlreadyReversedException`	Double reversal attempted
`LedgerEntryNotFoundException`	Entry not found
`DuplicatePostingException`	Duplicate posting detected
`InvalidTransactionException`	Transaction state is invalid

Architecture

This package follows the Atomic Architecture pattern (Layer 1):

Contracts: Interface definitions for domain contracts and repository patterns (CQRS)
Entities: Domain entities (Ledger, Transaction, etc.)
ValueObjects: Immutable data structures
Services: Pure business logic (LedgerService, TransactionService)
Enums: Type-safe enumerations
Exceptions: Domain-specific exceptions

License

MIT License

azaharizaman / nexus-general-ledger

Maintainers

Package info

Statistics

Security