PHPackages                             azaharizaman/nexus-cash-management - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. azaharizaman/nexus-cash-management

ActiveLibrary[Utility & Helpers](/categories/utility)

azaharizaman/nexus-cash-management
==================================

Atomic package for managing bank accounts, bank statement imports, cash reconciliation, and liquidity forecasting

v0.1.0-alpha1(1mo ago)00MITPHPPHP ^8.3

Since May 5Pushed 1mo agoCompare

[ Source](https://github.com/azaharizaman/nexus-cash-management)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-cash-management)[ RSS](/packages/azaharizaman-nexus-cash-management/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Nexus\\CashManagement
=====================

[](#nexuscashmanagement)

**Atomic, stateless package for managing bank accounts, bank statement imports, cash reconciliation, and liquidity forecasting—strictly decoupled from GL ownership.**

Overview
--------

[](#overview)

The `Nexus\CashManagement` package provides comprehensive cash and bank account management capabilities within the Nexus ERP ecosystem. It focuses on:

- **Bank Account Management**: Master data for company bank accounts with multi-currency support
- **Statement Import**: Configurable CSV import with duplicate detection and validation
- **Automatic Reconciliation**: AI-assisted matching of bank transactions to ERP records (Payments, Receipts, GL entries)
- **Manual Reconciliation**: Review and approval workflow for unmatched transactions
- **Cash Flow Forecasting**: Deterministic and AI-powered multi-scenario forecasting
- **Cash Position Tracking**: Real-time cash position across all bank accounts

Core Philosophy
---------------

[](#core-philosophy)

### Strict Decoupling

[](#strict-decoupling)

This package adheres to the **"Logic in Packages, Implementation in Applications"** principle:

- **Framework-Agnostic**: Pure PHP with zero Laravel dependencies
- **Contract-Driven**: All dependencies expressed via interfaces
- **Stateless Operations**: No GL posting—only reconciliation and classification
- **Integration via Events**: Consumes `Nexus\Import` events for statement data

### Separation of Concerns

[](#separation-of-concerns)

```
Nexus\Import          → Parses CSV files → Emits StatementLineDTO[]
Nexus\CashManagement  → Consumes DTOs   → Creates BankStatement entities → Matches transactions
Nexus\Finance         → Receives post commands → Creates Journal Entries

```

Architecture
------------

[](#architecture)

### Key Design Decisions

[](#key-design-decisions)

1. **AuditLogger for Timeline** (V1): All reconciliation events logged for user-facing timeline
2. **EventStream Optional** (V2): Available for large enterprises requiring SOX compliance and temporal queries
3. **Manual GL Posting**: Reconciliation engine creates `PendingAdjustment` entities; user manually posts to GL
4. **Auto-Reversal**: Rejected pending adjustments automatically reverse payment applications via workflow
5. **AI Governance**: Model versioning tracked in `PendingAdjustment` for explainability

### Integration Points

[](#integration-points)

- **`Nexus\Finance`**: GL account validation, journal entry posting
- **`Nexus\Receivable`**: Payment application matching and reversal
- **`Nexus\Payable`**: Payment matching for outflows
- **`Nexus\Period`**: Period validation for transaction dates
- **`Nexus\Currency`**: Multi-currency exchange rates (V2)
- **`Nexus\Sequencing`**: Auto-numbering for statements and reconciliations
- **`Nexus\Import`**: CSV file parsing and standardization
- **`Nexus\Setting`**: Feature flags and configuration
- **`Nexus\Workflow`**: High-value variance escalation and reversal approval
- **`Nexus\Intelligence`** (optional): AI-powered classification and forecasting
- **`Nexus\QueryEngine`** (optional): Cash Conversion Cycle and bank fee analysis

Features
--------

[](#features)

### Bank Account Management

[](#bank-account-management)

```
$bankAccount = $cashManager->createBankAccount(
    tenantId: $tenantId,
    accountCode: '1000-01',
    glAccountId: $glAccountId,
    accountNumber: '1234567890',
    bankName: 'Maybank',
    bankCode: 'MBB',
    accountType: BankAccountType::CHECKING,
    currency: 'MYR',
    csvImportConfig: [
        'date_column' => 'Transaction Date',
        'description_column' => 'Description',
        'debit_column' => 'Debit',
        'credit_column' => 'Credit',
        'balance_column' => 'Balance'
    ]
);
```

### Statement Import

[](#statement-import)

```
// Import via Nexus\Import package (emits FileImportedEvent)
// BankStatementImportedListener consumes event and creates entities

$result = $cashManager->reconcileStatement($statementId);

echo "Matched: {$result->getMatchedCount()}\n";
echo "Unmatched: {$result->getUnmatchedCount()}\n";
```

### Cash Flow Forecasting

[](#cash-flow-forecasting)

```
$parameters = ScenarioParametersVO::fromScenarioType(
    ForecastScenarioType::BASELINE,
    horizonDays: 90
);

$forecast = $cashFlowForecaster->forecast($tenantId, $parameters);

if ($forecast->hasNegativeBalance()) {
    // Alert: Liquidity risk detected
}
```

### Pending Adjustment Posting

[](#pending-adjustment-posting)

```
// User reviews unmatched transaction
$cashManager->postPendingAdjustment(
    pendingAdjustmentId: $adjustmentId,
    glAccount: '6200', // Bank Fees Expense
    postedBy: $userId
);

// If user rejects (wrong match):
$cashManager->rejectPendingAdjustment(
    pendingAdjustmentId: $adjustmentId,
    reason: 'Incorrect match - customer deposit',
    rejectedBy: $userId
);
// Triggers automatic payment application reversal + GL workflow
```

Value Objects
-------------

[](#value-objects)

- **`BankAccountNumber`**: Validated bank account with IBAN/SWIFT support
- **`StatementPeriod`**: Date range with overlap detection
- **`ReconciliationTolerance`**: Amount/date variance thresholds
- **`CashPosition`**: Point-in-time balance snapshot
- **`CSVColumnMapping`**: Import configuration
- **`ScenarioParametersVO`**: Forecast scenario parameters
- **`ForecastResultVO`**: Persistable forecast output
- **`StatementHash`**: Cryptographic deduplication
- **`AIModelVersion`**: Semantic versioning for AI models

Enums
-----

[](#enums)

- **`BankAccountType`**: CHECKING, SAVINGS, CREDIT\_CARD, MONEY\_MARKET, LINE\_OF\_CREDIT
- **`BankAccountStatus`**: ACTIVE, INACTIVE, CLOSED, SUSPENDED
- **`BankTransactionType`**: DEPOSIT, WITHDRAWAL, TRANSFER, FEE, INTEREST, etc.
- **`ReconciliationStatus`**: PENDING, MATCHED, VARIANCE\_REVIEW, RECONCILED, UNMATCHED, REJECTED
- **`MatchingConfidence`**: HIGH, MEDIUM, LOW, MANUAL
- **`ForecastScenarioType`**: OPTIMISTIC, BASELINE, PESSIMISTIC, CUSTOM

Exceptions
----------

[](#exceptions)

- **`BankAccountNotFoundException`**
- **`DuplicateStatementException`**
- **`PartialOverlapException`**
- **`ReconciliationException`**
- **`ReversalRequiredException`**
- **`InvalidStatementFormatException`**
- **`UnmatchedTransactionsException`**

Multi-Currency Support (V2)
---------------------------

[](#multi-currency-support-v2)

The package schema is V2-ready with nullable columns:

- `transaction_currency`
- `exchange_rate`
- `functional_amount`

Multi-currency activation requires:

```
$featureManager->isEnabled('multi_currency_banking')
```

Dependencies
------------

[](#dependencies)

- `azaharizaman/nexus-finance` - GL integration
- `azaharizaman/nexus-receivable` - Payment application
- `azaharizaman/nexus-payable` - Payment matching
- `azaharizaman/nexus-period` - Period validation
- `azaharizaman/nexus-currency` - Exchange rates
- `azaharizaman/nexus-sequencing` - Auto-numbering
- `azaharizaman/nexus-import` - Statement parsing
- `azaharizaman/nexus-setting` - Configuration
- `azaharizaman/nexus-workflow` - Approval processes

Optional Dependencies
---------------------

[](#optional-dependencies)

- `azaharizaman/nexus-intelligence` - AI classification/forecasting
- `azaharizaman/nexus-query-engine` - KPI calculation

Installation
------------

[](#installation)

```
composer require azaharizaman/nexus-cash-management:"*@dev"
```

📖 Documentation
---------------

[](#-documentation)

### Package Documentation

[](#package-documentation)

- **[Getting Started Guide](docs/getting-started.md)** - Quick start guide with prerequisites, concepts, and first integration
- **[API Reference](docs/api-reference.md)** - Complete documentation of all interfaces, value objects, enums, and exceptions
- **[Integration Guide](docs/integration-guide.md)** - Laravel and Symfony integration examples with complete setup
- **[Basic Usage Example](docs/examples/basic-usage.php)** - Import statement, auto-reconcile, approve/reject adjustments
- **[Advanced Usage Example](docs/examples/advanced-usage.php)** - Cash flow forecasting, AI feedback, high-value workflows, multi-currency

### Additional Resources

[](#additional-resources)

- `IMPLEMENTATION_SUMMARY.md` - Implementation progress, metrics, and architecture details
- `REQUIREMENTS.md` - Detailed requirements (58 requirements, 96.6% complete)
- `TEST_SUITE_SUMMARY.md` - Test coverage strategy and recommendations
- `VALUATION_MATRIX.md` - Package valuation metrics ($140,576 estimated value)
- See root `ARCHITECTURE.md` for overall system architecture

License
-------

[](#license)

MIT License. See LICENSE file for details.

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance93

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

36d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/117408?v=4)[Azahari Zaman](/maintainers/azaharizaman)[@azaharizaman](https://github.com/azaharizaman)

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/azaharizaman-nexus-cash-management/health.svg)

```
[![Health](https://phpackages.com/badges/azaharizaman-nexus-cash-management/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-cash-management)
```

###  Alternatives

[symfony/lock

Creates and manages locks, a mechanism to provide exclusive access to a shared resource

515135.1M619](/packages/symfony-lock)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[phpro/soap-client

A general purpose SoapClient library

8955.9M52](/packages/phpro-soap-client)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

562565.8k41](/packages/ecotone-ecotone)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

744284.3k34](/packages/civicrm-civicrm-core)[illuminate/broadcasting

The Illuminate Broadcasting package.

7126.9M199](/packages/illuminate-broadcasting)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)