feat: reorganize offline inst-calculation

- implement unit-tests
- add DateTime wrapper
- throw proper exceptions

ORCA-1973

Squashed commit of the following:

commit d9038a95afac8c972e593daa7e6234da0f382647
Author: Eduardo Iriarte-Mendez <eduardo.iriarte-mendez@ratepay.com>
Date:   Fri Jan 28 18:11:50 2022 +0100

    feat: reorganize offline inst-calculation

    - implement unit-tests
    - add DateTime wrapper
    - throw proper exceptions

src/Exception/OfflineInstalmentCalculationException.php

@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * Ratepay PHP-Library
+ *
+ * This document contains trade secret data which are the property of
+ * Ratepay GmbH, Berlin, Germany. Information contained herein must not be used,
+ * copied or disclosed in whole or part unless permitted in writing by Ratepay GmbH.
+ * All rights reserved by Ratepay GmbH.
+ *
+ * Copyright (c) 2019 Ratepay GmbH / Berlin / Germany
+ */
+
+namespace RatePAY\Exception;
+
+class OfflineInstalmentCalculationException extends \Exception
+{
+}

src/Service/DateTime/DateTime.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * Ratepay PHP-Library
+ *
+ * This document contains trade secret data which are the property of
+ * Ratepay GmbH, Berlin, Germany. Information contained herein must not be used,
+ * copied or disclosed in whole or part unless permitted in writing by Ratepay GmbH.
+ * All rights reserved by Ratepay GmbH.
+ *
+ * Copyright (c) 2019 Ratepay GmbH / Berlin / Germany
+ */
+
+namespace RatePAY\Service\DateTime;
+
+use DateTime as InternalDateTime;
+
+/**
+ * DateTime wrapper class inspired by Carbon.
+ * It provides handy accessors and allow isolation of internal classes during testing.
+ */
+class DateTime extends InternalDateTime
+{
+    use DateTimeTesting;
+    use DateTimeModifiers;
+    use DateTimeCalculators;
+
+    /**
+     * @return DateTime
+     */
+    public static function now()
+    {
+        return self::hasTestingNow() ? self::getTestingNow() : new DateTime();
+    }
+
+    /**
+     * @return DateTime
+     */
+    public static function today()
+    {
+        return self::hasTestingNow() ? self::getTestingNow()->setTime(0, 0) : new DateTime('today');
+    }
+}

src/Service/DateTime/DateTimeCalculators.php

@@ -0,0 +1,57 @@
+<?php
+
+/*
+ * Ratepay PHP-Library
+ *
+ * This document contains trade secret data which are the property of
+ * Ratepay GmbH, Berlin, Germany. Information contained herein must not be used,
+ * copied or disclosed in whole or part unless permitted in writing by Ratepay GmbH.
+ * All rights reserved by Ratepay GmbH.
+ *
+ * Copyright (c) 2019 Ratepay GmbH / Berlin / Germany
+ */
+
+namespace RatePAY\Service\DateTime;
+
+trait DateTimeCalculators
+{
+    /**
+     * @param DateTime $dateTime related date time to perform calculation
+     *
+     * @return int|float difference between dates in seconds
+     */
+    public function diffInSeconds($dateTime)
+    {
+        return $this->getTimestamp() - $dateTime->getTimestamp();
+    }
+
+    /**
+     * @param DateTime $dateTime related date time to perform calculation
+     *
+     * @return int|float difference between dates in minutes
+     */
+    public function diffInMinutes($dateTime)
+    {
+        return $this->diffInSeconds($dateTime) / 60;
+    }
+
+    /**
+     * @param DateTime $dateTime related date time to perform calculation
+     *
+     * @return int|float difference between dates in minutes
+     */
+    public function diffInHours($dateTime)
+    {
+        return $this->diffInMinutes($dateTime) / 60;
+    }
+
+    /**
+     * @param DateTime $dateTime related date time to perform calculation
+     *
+     * @return int|float difference between dates in minutes
+     */
+    public function diffInDays($dateTime)
+    {
+        return $this->diffInHours($dateTime) / 24;
+    }
+}

src/Service/DateTime/DateTimeModifiers.php

@@ -0,0 +1,101 @@
+<?php
+
+/*
+ * Ratepay PHP-Library
+ *
+ * This document contains trade secret data which are the property of
+ * Ratepay GmbH, Berlin, Germany. Information contained herein must not be used,
+ * copied or disclosed in whole or part unless permitted in writing by Ratepay GmbH.
+ * All rights reserved by Ratepay GmbH.
+ *
+ * Copyright (c) 2019 Ratepay GmbH / Berlin / Germany
+ */
+
+namespace RatePAY\Service\DateTime;
+
+trait DateTimeModifiers
+{
+    /**
+     * @param int $day days of month to set
+     *
+     * @return DateTime
+     */
+    public function setDay($day)
+    {
+        $date = $this->getDateFields();
+
+        return $this->setDate($date->year, $date->month, $day);
+    }
+
+    /**
+     * @param int $daysOffset number of days to be added
+     *
+     * @return DateTime
+     */
+    public function addDays($daysOffset)
+    {
+        $date = $this->getDateFields();
+
+        return $this->setDate($date->year, $date->month, $date->day + $daysOffset);
+    }
+
+    /**
+     * @param int $month month of year to set
+     *
+     * @return DateTime
+     */
+    public function setMonth($month)
+    {
+        $date = $this->getDateFields();
+
+        return $this->setDate($date->year, $month, $date->day);
+    }
+
+    /**
+     * @param int $monthsOffset number of months to be added
+     *
+     * @return DateTime
+     */
+    public function addMonths($monthsOffset)
+    {
+        $date = $this->getDateFields();
+
+        return $this->setDate($date->year, $date->month + $monthsOffset, $date->day);
+    }
+
+    /**
+     * @param int $year year to set
+     *
+     * @return DateTime
+     */
+    public function setYear($year)
+    {
+        $date = $this->getDateFields();
+
+        return $this->setDate($year, $date->month, $date->day);
+    }
+
+    /**
+     * @param int $yearsOffset number of years to be added
+     *
+     * @return DateTime
+     */
+    public function addYears($yearsOffset)
+    {
+        $date = $this->getDateFields();
+
+        return $this->setDate($date->year + $yearsOffset, $date->month, $date->day);
+    }
+
+    /**
+     * @return object
+     */
+    private function getDateFields()
+    {
+        return (object) [
+            'year' => (int) $this->format('Y'),
+            'month' => (int) $this->format('m'),
+            'day' => (int) $this->format('d'),
+        ];
+    }
+}

src/Service/DateTime/DateTimeTesting.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * Ratepay PHP-Library
+ *
+ * This document contains trade secret data which are the property of
+ * Ratepay GmbH, Berlin, Germany. Information contained herein must not be used,
+ * copied or disclosed in whole or part unless permitted in writing by Ratepay GmbH.
+ * All rights reserved by Ratepay GmbH.
+ *
+ * Copyright (c) 2019 Ratepay GmbH / Berlin / Germany
+ */
+
+namespace RatePAY\Service\DateTime;
+
+trait DateTimeTesting
+{
+    /**
+     * @var DateTime
+     */
+    private static $_testingNow;
+
+    /**
+     * It sets a custom DateTime instance as the "now" value.
+     * This handy hook allows performing tests without side effects.
+     *
+     * @return DateTime
+     */
+    public static function withTestingNow(DateTime $dateTime)
+    {
+        self::$_testingNow = $dateTime;
+
+        return self::now();
+    }
+
+    /**
+     * It restores testing now to empty value and allows normal DateTime functionality.
+     *
+     * @return void
+     */
+    public static function resetTestingNow()
+    {
+        self::$_testingNow = null;
+    }
+
+    /**
+     * @return bool
+     */
+    private static function hasTestingNow()
+    {
+        return isset(self::$_testingNow);
+    }
+
+    /**
+     * @return DateTime
+     */
+    private static function getTestingNow()
+    {
+        return clone self::$_testingNow;
+    }
+}

src/Service/Math.php

@@ -18,6 +18,11 @@
  */
 class Math
 {
+    public static function isZero($number, $precission = 2)
+    {
+        return round($number, $precission) === 0.0;
+    }
+
     /**
      * @param float     $netPrice
      * @param float|int $taxPercentage
@@ -37,4 +42,15 @@ public static function netToGross($netPrice, $taxPercentage, $round = false)
 
         return $rounded;
     }
+
+    /**
+     * @param float $annualInterestRate annual percentage interest rate
+     * @param float $interval           Fraction of a year
+     *
+     * @return float|int
+     */
+    public static function interestByInterval($annualInterestRate, $interval)
+    {
+        return pow((1 + ($annualInterestRate / 100)), $interval) - 1;
+    }
 }