Add more methods to DateRange (#9)

* Add date interval factory and date period factory

* Add DateRange split

* Adjust docs

Author: slavcodev

src/DateRange.php

@@ -10,9 +10,12 @@
 
 namespace Zee\DateRange;
 
+use DateInterval;
+use DatePeriod;
 use DateTimeImmutable;
 use DateTimeInterface;
 use JsonSerializable;
+use Traversable;
 use Zee\DateRange\States\RangeState;
 use Zee\DateRange\States\UndefinedRange;
 
@@ -171,4 +174,37 @@ public function isEnded(): bool
     {
         return $this->hasEndTime() && $this->state->compareEndTime(new DateTimeImmutable()) < 0;
     }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getDateInterval(): DateInterval
+    {
+        return $this->getStartTime()->diff($this->getEndTime());
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getDatePeriod(DateInterval $interval, int $option = 0): DatePeriod
+    {
+        return new DatePeriod($this->getStartTime(), $interval, $this->getEndTime(), $option);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function split(DateInterval $interval): Traversable
+    {
+        $startDate = $this->getStartTime();
+        $endDate = $this->getEndTime();
+        $period = $this->getDatePeriod($interval, DatePeriod::EXCLUDE_START_DATE);
+
+        foreach ($period as $date) {
+            yield new DateRange($startDate, $date);
+            $startDate = $date;
+        }
+
+        yield new DateRange($startDate, $endDate);
+    }
 }

src/DateRangeInterface.php

@@ -10,7 +10,10 @@
 
 namespace Zee\DateRange;
 
+use DateInterval;
+use DatePeriod;
 use DateTimeInterface;
+use Traversable;
 
 /**
  * Date range interface.
@@ -101,4 +104,37 @@ public function isStarted(): bool;
      * @return bool
      */
     public function isEnded(): bool;
+
+    /**
+     * Returns the range interval.
+     *
+     * @return DateInterval
+     */
+    public function getDateInterval(): DateInterval;
+
+    /**
+     * Returns date period according to a given interval.
+     *
+     * Allows iteration over the range.
+     *
+     * @param DateInterval $interval
+     * @param int $option
+     *
+     * @return DatePeriod|DateTimeInterface[]
+     */
+    public function getDatePeriod(DateInterval $interval, int $option = 0): DatePeriod;
+
+    /**
+     * Splits range into smaller ranges according to a given interval.
+     *
+     * All resulting ranges (except first and last) starts on same date as previously ends.
+     * The first starts on same date as parent range, last ends on same date as parent range.
+     *
+     * Keep in mind that the last range may be equal or lesser than the given interval.
+     *
+     * @param DateInterval $interval
+     *
+     * @return Traversable
+     */
+    public function split(DateInterval $interval): Traversable;
 }

tests/DateRangeTest.php

@@ -10,6 +10,7 @@
 
 namespace Zee\DateRange;
 
+use DateInterval;
 use DateTimeImmutable;
 use DateTimeZone;
 use DomainException;
@@ -279,4 +280,52 @@ public function dumpRange()
 
         self::assertNotContains('state', $dump);
     }
+
+    /**
+     * @test
+     */
+    public function getDateInterval()
+    {
+        $yesterday = new DateTimeImmutable('-1 day');
+        $tomorrow = new DateTimeImmutable('+1 day');
+        $range = new DateRange($yesterday, $tomorrow);
+        $interval = $range->getDateInterval();
+
+        self::assertSame(2, $interval->days);
+    }
+
+    /**
+     * @test
+     */
+    public function getDatePeriod()
+    {
+        $yesterday = new DateTimeImmutable('-1 day');
+        $tomorrow = new DateTimeImmutable('+1 day');
+        $range = new DateRange($yesterday, $tomorrow);
+        $interval = new DateInterval('P1D');
+        $period = $range->getDatePeriod($interval);
+
+        self::assertSame($range->getStartTime()->getTimestamp(), $period->getStartDate()->getTimestamp());
+        self::assertSame($range->getEndTime()->getTimestamp(), $period->getEndDate()->getTimestamp());
+        self::assertSame(2, iterator_count($period));
+    }
+
+    /**
+     * @test
+     */
+    public function splitRange()
+    {
+        $yesterday = new DateTimeImmutable('-1 day');
+        $tomorrow = new DateTimeImmutable('+1 day');
+        $range = new DateRange($yesterday, $tomorrow);
+        $interval = new DateInterval('P1D');
+
+        $ranges = $range->split($interval);
+
+        self::assertSame(2, iterator_count($ranges));
+
+        foreach ($range->split($interval) as $range) {
+            self::assertInstanceOf(DateRange::class, $range);
+        }
+    }
 }