[DateTime] Add comments for DateTime adMonths() method

.travis.yml

@@ -10,7 +10,7 @@ php:
   - 5.5
   - 5.6
   - 7
-  - hhvm
+  - 7.1
 
 matrix:
   allow_failures:

src/DateTime/DateTime.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright (c) 2015 GOTO Hidenori <hidenorigoto@gmail.com>,
+ * Copyright (c) 2017 GOTO Hidenori <hidenorigoto@gmail.com>,
  * All rights reserved.
  *
  * This file is part of Domain Commons.
@@ -13,6 +13,7 @@
 namespace PHPMentors\DomainCommons\DateTime;
 
 use DateTimeImmutable;
+use PHPMentors\DomainCommons\DateTime\Exception\UnsupportedCalculation;
 
 class DateTime extends DateTimeImmutable
 {
@@ -24,6 +25,15 @@ public function addDays($days)
         return new $class(date('Y-m-d H:i:s', strtotime($daysStr, $this->getTimestamp())));
     }
 
+    /**
+     * @param  int       $months
+     * @return DateTime
+     * @throws UnsupportedCalculation
+     *
+     * NOTE: This method throws UnsupportedCalculation exception when
+     *       the day of the result is not equal to the original date.
+     *       Don't forget to handle this situation before calling this method.
+     */
     public function addMonths($months)
     {
         $class = static::class;
@@ -32,7 +42,7 @@ public function addMonths($months)
         $newInstance = new $class(date('Y-m-d H:i:s', strtotime($monthsStr, $this->getTimestamp())));
 
         if ($newInstance->format('d') != $this->format('d')) {
-            throw new \RuntimeException();
+            throw new UnsupportedCalculation();
         }
 
         return $newInstance;

src/DateTime/Exception/UnsupportedCalculation.php

@@ -0,0 +1,18 @@
+<?php
+/*
+ * Copyright (c) 2017 GOTO Hidenori <hidenorigoto@gmail.com>,
+ * All rights reserved.
+ *
+ * This file is part of Domain Commons.
+ *
+ * This program and the accompanying materials are made available under
+ * the terms of the BSD 2-Clause License which accompanies this
+ * distribution, and is available at http://opensource.org/licenses/BSD-2-Clause
+ */
+
+namespace PHPMentors\DomainCommons\DateTime\Exception;
+
+class UnsupportedCalculation extends \RuntimeException
+{
+
+}

tests/DateTime/DateTimeTest.php

@@ -16,6 +16,9 @@ class DateTimeTest extends \PHPUnit_Framework_TestCase
 {
     /**
      * @test
+     * @param string $dateStr
+     * @param int    $days
+     * @param string $expected
      * @dataProvider addDaysData
      */
     public function addDays($dateStr, $days, $expected)
@@ -37,16 +40,15 @@ public function addDaysData()
 
     /**
      * @test
-     * @dataProvider addMOnthsData
+     * @param string  $dateStr
+     * @param int     $months
+     * @param string  $expected
+     * @dataProvider  addMonthsData
      */
     public function addMonths($dateStr, $months, $expected)
     {
         $date = new DateTime($dateStr);
 
-        if ($expected === null) {
-            $this->setExpectedException('RuntimeException');
-        }
-
         $added = $date->addMonths($months);
 
         $this->assertThat($added->format('Y-m-d'), $this->equalTo($expected));
@@ -56,9 +58,36 @@ public function addMonthsData()
     {
         return [
             ['2015-03-21',  3, '2015-06-21'],
-            ['2015-01-30',  1, null],
+            ['2017-05-30',  1, '2017-06-30'],
             ['2014-12-19',  5, '2015-05-19'],
             ['2014-12-19', -2, '2014-10-19'],
         ];
     }
+
+    /**
+     * @test
+     * @param string  $dateStr
+     * @param int     $months
+     * @dataProvider  addMonthsThrowsExceptionData
+     * @expectedException \PHPMentors\DomainCommons\DateTime\Exception\UnsupportedCalculation
+     */
+    public function addMonthsThrowsException($dateStr, $months)
+    {
+        $date = new DateTime($dateStr);
+
+        $date->addMonths($months);
+
+        $this->fail();
+    }
+
+    public function addMonthsThrowsExceptionData()
+    {
+        return [
+            ['2015-01-30',  1],
+            ['2017-05-31',  1],
+            ['2017-01-29',  1],
+            ['2017-01-30',  1],
+            ['2017-01-31',  1],
+        ];
+    }
 }