Coder Social home page Coder Social logo

php-apr-calculator's Introduction

Average percentage rate of charge calculator for PHP

Build status

This library is an average percentage rate of charge (APR or APRC) calculator compliant* with European Commission Directive 2014/17/EU (‘Mortgage Credit Directive’, MCD) and European Commission Directive 2008/48/EC (‘Consumer Credit Directive’, CCD).

The APR is essentially how much your borrowing will cost over the period of an average year, over the term of your debt. It takes into account interest charged as well as any additional fees (such as arrangement fees, or annual fees) you’ll have to pay. It also considers the frequency with which interest is charged on your borrowing, as this as an impact on how much you will pay as well.

The code and logic was initially ported from a similar C# library, which claims compliance with the British Financial Conduct Authority (FCA) regulations, particularly the FCA MBOC 10.3 Formular for calculating APR. I believe that compliance with this regulation, as well as with MCOB 10A.2 Formular for calculating APRC, is also safe to assume.

More information about the original library, as well as some examples of its usage, are available in its author's archived weblog entry.

How to use

Install the library using composer:

$ composer require rq/apr-calculator

Naturally, you can download the archive of this repository if you don’t want to or can’t use Composer for some reason.

Then in your code, create an instance of the Calculator class by passing the amount of the first advance to its constructor:

use RQ\APRCalculator\Calculator;

...

$calculator = new Calculator(200000);

Once that is done, you must add all instalments (payments and advances) that are to be included in the calculation. What exactly these instalments are will depend completely on your use-case (type of the loan, its duration and other terms).

A single instalment may be added by using one of the following methods:

// $calculator->addAdvance(float $amount, float $daysAfterFirstAdvance): self
// $calculator->addPayment(float $amount, float $daysAfterFirstAdvance): self
// $calculator->addInstalment(float $amount, float $daysAfterFirstAdvance, int $type = Calculator::TYPE_PAYMENT): self
$calculator->addAdvance(4000, 30);
$calculator->addPayment(4000, 30);
$calculator->addInstalment(4000, 30);

A series of regular identical instalments may be added like this:

// $calculator->addRegularAdvances(float $amount, float $numberOfAdvances, float $daysBetweenAdvances, float $daysAfterFirstAdvance = 0): self
// $calculator->addRegularPayments(float $amount, float $numberOfPayments, float $daysBetweenPayments, float $daysAfterFirstAdvance = 0): self
// $calculator->aaddRegularInstalments(float $amount, float $numberOfInstalments, float $daysBetweenInstalments, float $daysAfterFirstAdvance = 0, int $type = Calculator::TYPE_PAYMENT): self
$calculator->addRegularAdvances(600, 12, Calculator::FREQUENCY_MONTHLY);
$calculator->addRegularPayments(600, 12, Calculator::FREQUENCY_MONTHLY);
$calculator->addRegularInstalments(600, 12, Calculator::FREQUENCY_MONTHLY);

Once all instalments have been added, just call the calculate() method to get the APR back as a float:

// $calculator->calculate(float $guess = 0, int $round = self::DEFAULT_PRECISION): float
$apr = $calculator->calculate()

For your convenience, there is also a static create() method available, and all of add*() methods chainable, thus if you prefer, you can also calculate the APR without even assigning the calculator to a variable, like this:

$apr = Calculator::create(200000)
    ->addPayment(4000, 0)
    ->addRegularPayments(1432.86, 240, Calculator::FREQUENCY_MONTHLY)
    ->calculate();

If there is only one (initial) advance and one payment in your scenario, you can further save one call by calling the calculateForSinglePayment() method right after you instantiate the class, like this:

// $calculator->calculateForSinglePayment(float $payment, int $daysAfterAdvance, int $round = self::DEFAULT_PRECISION): float
$apr = Calculator::create(100)
    ->calculateForSinglePayment(120, 14);

A document with APR calculation examples published by the EC in 2015 is available in the doc/ folder. All of its examples have been rewritten as PhpSpec tests under spec/. They not only help test the code, but may also serve as illustration of how to use the library. Additionally, a number of tests written for the original C# library have also been ported and are available there.


* Note of caution: at least according to the EC directives, in some cases the calculated APR will depend on the actual date that it is claimed on (leap years are involved in some cases). This is currently not taken into account by the calculator, and a year of 365.25 days is assumed. This means that there is a narrow chance of the result of the calculation actually being incorrect.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.