FeeCollection

Laravel fee workflow package for scheduled payments, invoices, receipts, credit notes, statement history, wallet balances, and optional PDF documents.

FeeCollection is a Laravel package for fee workflows:

• register upcoming payments
• create invoices and receipts
• create manual credit notes
• split payments
• detect overdue payments and generate due invoices
• keep account statements recalculated
• track one wallet balance row per payable model
• optionally generate/store invoice/receipt PDFs

See the documentation below, or browse the full documentation site:

https://3mad0o.github.io/fee-collection-documentation/

Table of Contents

• Requirements
• Installation
• Getting Started
• Configuration
• Core Concepts
• Usage Examples
• PDF Documents
• Events
• API Quick Reference
• What Gets Stored
• License

Requirements

• PHP 8.3+
• Laravel 13+

Installation

Install package in your Laravel app:

If your app does not auto-discover providers, register:

For PDF generation support (optional):

Publish Package Files

Publish config:

Publish default PDF blade views:

Published views path:

resources/views/vendor/fee-collection/pdf

Migrations

Run migrations:

This creates:

• upcoming_payments
• account_statements
• account_statement_upcoming_payments
• wallet_transactions (single row per walletable with current balance)

Getting Started

Setup Model

Add UseFeeable trait to any Eloquent model (for example User):

After this, the model can register payments, create receipts, generate due invoices, query statements, and read its wallet balance.

Configuration

File: config/fee_collection.php

Notes

• account_statements.number stores numeric value only.
• Prefix/suffix are added on retrieval via formatted_number.
• If pdf.enabled = true, generated PDF path is saved in account_statements.document.
• auto_invoice_on_receipt may be overridden per receipt call.
• Credit notes are always manual. Splitting a payment never creates a credit note automatically.

Core Concepts

FeeCollection is built around payable models, upcoming payments, account statements, and wallet balances.

Payable Models

Any Eloquent model using UseFeeable can own fee workflows. Typical examples include User, Student, Customer, and Tenant.

The trait adds methods for payment registration, statement access, wallet balance checks, overdue detection, and due invoice generation.

Upcoming Payments

An upcoming payment represents a scheduled amount due on a future date.

Upcoming payments can be:

• registered from a payable model
• invoiced manually
• receipted manually
• split into child payments
• detected as overdue
• invoiced automatically when due

Account Statements

Account statements represent financial documents and history entries such as invoices, receipts, and credit notes.

Statements include a status field for reporting and filtering.

Wallet Balance

The package tracks one wallet balance row per payable model in wallet_transactions.

Credit Notes

Credit notes are created from invoices. A credit note:

• references the original invoice through reference_id
• uses a negative amount
• changes the original invoice status to credited

Credit notes are not created automatically during payment splitting.

Voided Invoices

A voided invoice is excluded from balance recalculation.

Use voiding only for invoices that should be killed internally before customer settlement.

Usage Examples

1) Create receipt, then register payments (wallet consumption flow)

If wallet balance is enough, registered payments can be invoiced automatically.

Disable receipt-driven invoice generation per call:

2) Manual invoice and receipt on one upcoming payment

3) Split an upcoming payment

If the original payment already had an invoice, create the credit note manually:

4) Create a credit note

Credit notes:

• can only be created from invoices
• reference the original invoice through reference_id
• use a negative amount
• move the original invoice status to credited

5) Void an invoice

Voided invoices are excluded from balance recalculation. Use this only for invoices that should be killed internally before customer settlement.

6) Detect overdue payments

An overdue payment has a due date before today, still has remaining amount, and has no linked receipt.

7) Generate invoices due today

Scheduler example:

8) Statement status

Statements include a status field for filtering/reporting:

• issued
• paid
• overdue
• credited
• voided

Status is a reporting helper. Balances are still calculated from statement debit/credit values, excluding voided invoices.

9) List statements and check wallet balance

Events

The package dispatches these events after successful changes:

• Emad\FeeCollection\Events\InvoiceCreated
• Emad\FeeCollection\Events\ReceiptCreated
• Emad\FeeCollection\Events\CreditNoteCreated
• Emad\FeeCollection\Events\PaymentOverdue
• Emad\FeeCollection\Events\PaymentSplit
• Emad\FeeCollection\Events\InvoiceVoided

Common uses include customer notifications, internal audit logs, reporting updates, accounting exports, and webhook dispatching.

PDF Documents

FeeCollection can generate and store PDF documents for invoices, receipts, and credit notes.

Install DomPDF support:

PDF generation is controlled by config/fee_collection.php:

Useful environment variables:

Configure the Blade views used for generated documents:

Generate PDF manually

When PDF generation is enabled, the generated PDF path is saved in account_statements.document.

API Quick Reference

Payable model methods

Upcoming payment methods

Statement methods

What Gets Stored

• account_statements.number: numeric sequence (no prefix/suffix)
• account_statements.document: stored PDF relative path (when enabled)
• account_statements.reference_id: original invoice for credit notes
• account_statements.status: reporting status
• account_statements.voided_at: timestamp for voided invoices
• account_statements.void_reason: reason for voiding
• wallet_transactions.balance: current wallet balance for the payable

License

MIT