jn-devops/payment

Homeful Payment Package

v1.3.3 2025-03-25 08:08 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0||^11.0
• jarouche/financial: ^2.1
• jn-devops/common: ^1.1
• spatie/laravel-data: ^4.7
• spatie/laravel-package-tools: ^1.16
• whitecube/php-prices: ^3.0

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^9.0.0||^8.22.0
• pestphp/pest: ^2.34
• pestphp/pest-plugin-arch: ^2.7
• pestphp/pest-plugin-laravel: ^2.3
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1
• phpstan/phpstan-phpunit: ^1.3
• spatie/laravel-ray: ^1.35

MIT

• Lester B. Hurtado

• payment
• laravel
• Homeful

README

The Homeful\Payment package provides a robust and testable abstraction layer for mortgage-related financial computations. It encapsulates the standard PMT and PV formulas using precise monetary operations via the whitecube/price and brick/money libraries.

📦 Features

• Compute monthly amortization with interest and term (PMT formula)
• Add-on fee handling (e.g. insurance, extra charges)
• Deductible fee support (e.g. rebates, adjustments)
• Compute present value from future payment streams (PV formula)
• Income requirement estimation based on configurable disposable income percentage
• Extensive test coverage and simulation datasets

✅ Installation

Ensure you have the following packages:

composer require whitecube/price brick/money jarouche/financial

🧮 Usage

📘 Basic PMT Calculation

use Homeful\Payment\Payment;
use Homeful\Payment\Class\Term;

$payment = (new Payment)
    ->setPrincipal(850000.0)
    ->setTerm(new Term(20)) // 20 years
    ->setInterestRate(6.25 / 100);

$monthly = $payment->getMonthlyAmortization();
echo $monthly->format(); // e.g. PHP 6,213.00

➕ Add-On Fees (e.g. Fire Insurance, MRI)

use Homeful\Common\Classes\AddOnFeeToPayment;

$payment->addAddOnFeeToPayment(new AddOnFeeToPayment('fire insurance', 100, false));
$payment->addAddOnFeeToPayment(new AddOnFeeToPayment('mortgage redemption insurance', 200, false));

➖ Deductible Fees (e.g. Promo Deduction)

use Homeful\Common\Classes\DeductibleFeeFromPayment;

$payment->addDeductibleFee(new DeductibleFeeFromPayment('promo', 125, true));

🧾 Income Requirement

echo $payment->getIncomeRequirement(); // e.g. PHP 20,710.00

💡 Present Value Calculation

use Homeful\Payment\PresentValue;
use Homeful\Payment\Class\Term;

$pv = (new PresentValue)
    ->setPayment(19978.48)
    ->setTerm(new Term(20))
    ->setInterestRate(7 / 100);

echo $pv->getDiscountedValue()->format(); // e.g. PHP 2,576,874.00

🧪 Testing

Unit and simulation tests available in /tests/Payment.

php artisan test --filter=Payment

Includes scenarios for:

• Edge case interest validation
• Max term validations
• Add-on and deductible modifier interactions
• Multiple amortization simulations

⚙️ Configuration

You may configure these via config/payment.php:

return [
    'default_percent_disposable_income' => 0.30,
    'max_years_to_pay' => 30,
    'max_months_to_pay' => 360,
];

📂 Data Transformation

Use PaymentData::fromObject($payment) to extract structured values like:

• principal
• term, cycle
• interest_rate
• monthly_amortization
• income_requirement

🧩 Traits

• HasAddOnFees
• HasDeductibleFees
• HasIncomeRequirement

These ensure modular responsibility and are shared across payment types.

🤝 Dependencies

• brick/money
• whitecube/price
• jarouche/financial

✨ Example Output

$payment = (new Payment)
    ->setPrincipal(2900000)
    ->setTerm(new Term(30))
    ->setInterestRate(6.75 / 100);

echo $payment->getMonthlyAmortization()->format(); // PHP 18,809.00

Behold, a new you awaits — one with precise mortgage computations and a testable financial layer.