Calculating annuity in PHP

A collegue asked me about calculating annuity payments on loans. So I had a quick look around and found many people asking the same thing. The concept might be simple but it seems a lot of people stumble when it comes t othe algorithm.

Most of what I found was online calculators. The Swedish site rantekalkyl.se does exactly what I figured I wanted. (I even found an incorrect solution published in a thread at the Swedish phpsidan.nu.)

So I created a small class that calculates the monthly payment as well as the actual interest and amortization for every payment. Partly because I am sure others can be interested in the solution and partly because I’d like the code quality checked by as many as possible I publish it here. Feel free to suggest improvements and additions.

I know PHPUnit test case would be a nice addition but I didn’t have the time today.

<?php 

/**
 * @version 1.0
 * @author Danne Lundqvist, http://www.dotvoid.com
 */

/**
 * Class Financial_AnnuityLoan
 */
class Financial_AnnuityLoan {

  /**
   * Number of periods per year
   * @var int
   */
  private $aP;

  /**
   * Total number of periods
   * @var int
   */
  private $tP;

  /**
   * Yearly interest rate in decimal
   * @var float
   */
  private $rate;

  /**
   * Debt amount
   * @var float
   */
  private $amount;

  /**
   * Monthly payment
   * @var float
   */
  private $monthlyPayment;

  /**
   * Period specification
   * @var array
   */
  private $periodSpec;

  /**
   * Constructor for Annuity
   * 
   * @param int $annualPeriods Number of periods per year
   * @param int $totalPeriods Total number of periods
   * @param float $interestRate Interest rate in decimal notation
   * @param float $amount Total amount of debt
   */
  public function __construct($annualPeriods, $totalPeriods, $interestRate, $amount) {
    $this->aP = $annualPeriods;
    $this->tP = $totalPeriods;
    $this->rate = $interestRate;
    $this->amount = $amount;

    $this->monthlyPayment = null;
    $this->periodSpecification = null;
  }

  /**
   * Calculate monthly payment for annuity loan
   *
   * @return float
   */
  public function monthlyPayment() {
    if ($this->monthlyPayment != null) {
      return $this->monthlyPayment;
    }

    $i = 1 / (1 + ($this->rate / $this->aP)); 
    $this->monthlyPayment = ((1 - $i) * $this->amount) / ($i * (1 - pow($i, $this->tP)));
    return $this->monthlyPayment;
  }

  /**
   * Calculate actual debt, interest and amount to pay each period
   *
   * Calculates the actual interest, amortization, and remaining debt for each period.
   * The method return an array with associative arrays, each with period, interest,
   * payment and debt elements.
   *
   * @return array
   */
  public function periodSpecification() {
    if ($this->periodSpec != null) {
      return $this->periodSpec;
    }

    $pmt = $this->monthlyPayment();
    $periodrate = $this->rate / $this->aP;
    $debt = $this->amount;

    $val = array();
    for ($i = 0; $i < $this->tP; $i++) {
      $interest = $debt * $periodrate;
      $payment = $pmt - $interest;
      $debt -= $payment;

      $val[] = array('period' => $i + 1,
                     'interest' => round($interest, 2),
                     'payment' => round($payment, 2),
                     'debt' => round($debt, 2));
    }

    $this->periodSpec = $val;
    return $val;
  }
}