turahe/ledger

A ledger management system for handling vouchers and invoices.

v1.3.3 2025-08-23 08:17 UTC

This package is auto-updated.

Last update: 2025-08-23 08:29:46 UTC


README

A comprehensive Laravel package for managing financial ledgers, invoices, vouchers, and payment tracking with PHP 8.4 support.

๐Ÿš€ Features

  • Invoice Management - Create, update, and track invoices with items and payments
  • Voucher System - Manage vouchers with expiration dates and status tracking
  • Payment Processing - Support for multiple payment methods including QRIS, e-wallets, and traditional methods
  • Multi-currency Support - Built-in currency handling with configurable defaults
  • User Tracking - Comprehensive audit trail with user stamps
  • Business Logic - Built-in methods for financial calculations and status checks
  • Modern PHP - Full PHP 8.4 compatibility with enums and modern syntax
  • Laravel Integration - Seamless integration with Laravel's ecosystem

๐Ÿ“‹ Requirements

  • PHP 8.4+
  • Laravel 12+
  • MySQL/PostgreSQL/SQLite

๐Ÿ”ง Installation

  1. Install the package via composer:

    composer require turahe/ledger
  2. Publish resources (migrations and config files):

    php artisan vendor:publish --provider="Turahe\\Ledger\\Providers\\LedgerServiceProvider"
  3. Execute migrations via the following command:

    php artisan migrate
  4. Done!

โš™๏ธ Configuration

The package configuration is located in config/ledger.php. You can customize:

  • Default currency
  • Payment method settings
  • Model class mappings
  • Database table names

๐Ÿ“š Usage

Creating an Invoice

use Turahe\Ledger\Models\Invoice;
use Turahe\Ledger\Services\LedgerService;

// Using the model directly
$invoice = Invoice::create([
    'model_id' => $user->id,
    'model_type' => User::class,
    'code' => 'INV-001',
    'total_invoice' => 1000.00,
    'due_date' => now()->addDays(30),
    'status' => 'pending',
    'currency' => 'IDR'
]);

// Using the service layer
$ledgerService = app(LedgerService::class);
$invoice = $ledgerService->createInvoice([
    'model_id' => $user->id,
    'model_type' => User::class,
    'code' => 'INV-001',
    'total_invoice' => 1000.00,
    'due_date' => now()->addDays(30)
]);

Adding Invoice Items

use Turahe\Ledger\Models\Invoice\Item;

$item = $invoice->items()->create([
    'name' => 'Product Name',
    'quantity' => 2,
    'unit_price' => 500.00,
    'total_price' => 1000.00,
    'description' => 'Product description'
]);

// Business logic methods
$subtotal = $item->getSubtotal();
$totalAmount = $item->getTotalAmount();
$discountPercentage = $item->getDiscountPercentage();

Processing Payments

use Turahe\Ledger\Models\Invoice\Payment;
use Turahe\Ledger\Enums\PaymentMethods;

$payment = $invoice->payments()->create([
    'amount' => 500.00,
    'payment_method' => PaymentMethods::E_WALLET_GOPAY,
    'payment_date' => now(),
    'status' => 'completed'
]);

// Check payment status
if ($payment->isCompleted()) {
    echo "Payment processed successfully";
}

Managing Vouchers

use Turahe\Ledger\Models\Voucher;

$voucher = Voucher::create([
    'model_id' => $user->id,
    'model_type' => User::class,
    'code' => 'VOUCHER-001',
    'total_value' => 500.00,
    'due_date' => now()->addDays(15),
    'status' => 'active',
    'currency' => 'IDR'
]);

// Business logic methods
if ($voucher->isExpired()) {
    echo "Voucher has expired";
}

$daysUntilExpiry = $voucher->getDaysUntilExpiry();
$formattedValue = $voucher->getTotalValueFormatted();

Using Query Scopes

use Turahe\Ledger\Models\Invoice;

// Find by code
$invoice = Invoice::byCode('INV-001')->first();

// Find by date range
$recentInvoices = Invoice::byDateRange(
    now()->subDays(30), 
    now()
)->get();

// Find by status
$pendingInvoices = Invoice::byStatus('pending')->get();

// Find by model
$userInvoices = Invoice::byModelType(User::class)
    ->byModelId($user->id)
    ->get();

Payment Methods

use Turahe\Ledger\Enums\PaymentMethods;

// Get methods by category
$qrisMethods = PaymentMethods::getByCategory('qris');
$eWalletMethods = PaymentMethods::getByCategory('e_wallet');

// Check method properties
if (PaymentMethods::E_WALLET_GOPAY->isDigital()) {
    echo "This is a digital payment method";
}

if (PaymentMethods::CASH->isInstant()) {
    echo "This is an instant payment method";
}

๐Ÿงช Testing

The package includes comprehensive test coverage. To run the tests:

# Run all tests
./vendor/bin/phpunit --testdox

# Run specific test suite
./vendor/bin/phpunit --testdox --filter=InvoiceTest

# Run with coverage
./vendor/bin/phpunit --coverage-text

Test Coverage

  • Unit Tests - Model methods, business logic, and enums
  • Feature Tests - Complete workflow testing
  • Business Logic Tests - Financial calculations and validations

๐Ÿ”„ Recent Optimizations

The package has been recently optimized with:

  • PHP 8.4 Enum Support - Modern enum syntax and utility methods
  • Enhanced Models - Improved relationships, casting, and business logic
  • Service Layer - Centralized business logic in LedgerService
  • Trait System - Reusable HasLedgerAttributes trait for common functionality
  • Interface Contracts - LedgerModelInterface for consistent model behavior
  • Custom Exceptions - Specific error handling for ledger operations
  • Improved Migrations - Fixed schema issues and added missing columns
  • Better Testing - Comprehensive test coverage with proper setup

๐Ÿ“ Package Structure

src/
โ”œโ”€โ”€ Enums/                 # Payment methods and transaction types
โ”œโ”€โ”€ Exceptions/            # Custom exception classes
โ”œโ”€โ”€ Models/                # Eloquent models
โ”‚   โ”œโ”€โ”€ Concerns/          # Reusable traits
โ”‚   โ”œโ”€โ”€ Contracts/         # Interface definitions
โ”‚   โ”œโ”€โ”€ Invoice/           # Invoice-related models
โ”‚   โ””โ”€โ”€ Voucher/           # Voucher-related models
โ”œโ”€โ”€ Providers/             # Service providers
โ””โ”€โ”€ Services/              # Business logic services

๐Ÿค Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

๐Ÿ“„ License

This package is open-sourced software licensed under the MIT license.

๐Ÿ†˜ Support

If you encounter any issues or have questions:

  • Check the issues page
  • Create a new issue with detailed information
  • Ensure you're using the latest version

๐Ÿ”— Related Packages

  • UserStamps - User tracking for models
  • ULID - ULID support for Laravel