README

This package encapsulates the mortgage loan processing logic of the Homeful platform. It manages everything from borrower evaluation to monthly amortization, income requirements, and cash-out computations. The design is modular, chainable, and test-driven.

Installation

composer require homeful/mortgage

✨ Features Overview

Encapsulated Mortgage Class: Central to processing and configuring a mortgage loan.
Modular Traits: Responsibilities are split across focused, reusable traits.
Supports Add-on & Deductible Fees: MRI, Fire Insurance, Consulting, Processing fees, etc.
Dynamic GMI & PV-based Eligibility: Computes present value from disposable income.
Test-driven: Includes comprehensive real-world loan scenarios with expected outputs.
Fluent API: Chainable configuration methods (setX()->setY()).

🔧 Trait Responsibilities

🔢 Financial Computation

HasContractPrice: Manages TCP (Total Contract Price)
HasDownPayment: Computes down payment and amortization
HasMiscellaneousFees: Additional fees (computed or set)
HasMultipliers: Interest rates, income multipliers
HasTerms: Manages loan balance terms

💸 Cash Flow Management

HasCashOuts: Abstract layer for any outgoing cash items
HasAddOnFeesToLoanAmortization: Adds MRI & Fire Insurance to monthly amortization

👥 Parties

HasProperty: Assigns & syncs Property instance
HasBorrower: Assigns borrower & GMI rules

🎁 Promotions

HasPromos: Low-cash-out promo logic
isPromotional(): Detects promotional packages

⚙️ Static Config

HasConfig: Reads default term, interest rate, borrower age from config

🧮 Computation Flow

Validation: Inputs validated using Laravel validator
Defaults: Loaded from Property and Borrower if not provided
Processing:
- Down Payment
- Balance Payment
- Miscellaneous Fees
- Cash Outs
- Loan Details (term, interest, income requirement)

🔍 Formula Highlights

Balance Payment = TCP – Down Payment
Loan Principal = Balance Payment + Balance Misc. Fees
Loan Amortization = Payment + (MRI + Fire Insurance if applicable)

✅ Eligibility Tools

getLoanDifference(): Checks if borrower can afford based on income
getPresentValueFromMonthlyDisposableIncomePayments(): PV computation using borrower income
getJointBorrowerDisposableMonthlyIncome(): Computes combined disposable income

🧪 Test Coverage

Includes over 15 real-world scenarios such as:

✅ Agapeya 70/50 Duplex @ 20, 25, and 30 years
✅ Ter-Je 2BR 40sqm @ 20, 25, 30 years
✅ Low-income housing simulation with ₱750K TCP
✅ Relaxed GMI multiplier cases (30% vs 35%)
✅ Promo: zero down payment + waived fees
✅ Add-on MRI + Fire Insurance added to monthly amortization
✅ Present Value edge cases
✅ GMI-based maximum loan calculations
✅ Full simulation using createWithTypicalBorrower(...)

Each test checks:

Down Payment (amount + amortization)
Balance Payment
Miscellaneous Fees (partial & full)
Loan Amount
Loan Amortization
GMI / Disposable Income & Present Value eligibility
Add-on and deductible fee mechanics
Cash out summaries
Promo eligibility flags

🧠 Design Insights

Event Driven: Traits dispatch events on update
Chainable API: Fluent configuration methods
Precision Math: Uses Brick\Money + Whitecube\Price
Compliance Ready: Validates ranges for fees, DP, terms
Fully Tested: Aligns with PMT, PV financial functions for accuracy

🔗 Key Integrations

Homeful\Payment\Payment: Loan logic & computation
Homeful\Property\Property: Provides TCP, MF %, etc.
Homeful\Borrower\Borrower: Age, income, region
Homeful\Common\Classes: Shared value object helpers

🧰 Usage

use Homeful\Mortgage\Mortgage;
use Homeful\Borrower\Borrower;
use Homeful\Property\Property;
use Homeful\Common\Classes\Input;
use Homeful\Mortgage\Data\MortgageData;
use Illuminate\Support\Carbon;
use Whitecube\Price\Price;

$params = [
    Input::WAGES => 50000,
    Input::TCP => 2500000,
    Input::PERCENT_DP => 5 / 100,
    Input::DP_TERM => 12,
    Input::BP_INTEREST_RATE => 7 / 100,
    Input::PERCENT_MF => 8.5 / 100,
    Input::BP_TERM => 20,
];

$property = (new Property)
    ->setTotalContractPrice(Price::of($params[Input::TCP], 'PHP'))
    ->setAppraisedValue(Price::of($params[Input::TCP], 'PHP'));

$borrower = (new Borrower($property))
    ->setBirthdate(Carbon::parse('1999-03-17'))
    ->setGrossMonthlyIncome($params[Input::WAGES]);

$mortgage = new Mortgage(property: $property, borrower: $borrower, params: $params);
$data = MortgageData::fromObject($mortgage);

dd($data->toArray());

📊 Summary

The Mortgage package serves as the computation core for:

Housing affordability simulations
Loan qualification engines
Down payment amortization planners
Present value loan caps
Promotional packages with waived fees
Cross-segment real estate products

Behold, a new you awaits – with well-structured mortgage processing 🏡✨

jn-devops / mortgage

Maintainers

Details