Prepare v0.3 (#15)

* Update CHANGELOG

* Update README

Author: slavcodev

CHANGELOG.md

@@ -18,13 +18,23 @@ Security - in case of vulnerabilities.
 
 _TBD_
 
+## [0.3.0] 2017-11-18
+
+### Added
+- Added new methods `getInterval`, `getPeriod`, `split`
+- Added `DateRangeProvider` interface and basic provider `FiniteDateRangeProvider`
+
+### Changed
+- Rename methods from using `time` ot `date`.
+- Refactored internals.
+
 ## [0.1.1] 2017-11-17
 
 ### Changed
 - Implement `State` pattern to control ranges objects.
 - Change JSON representation to array instead of string in previous version.
 
-### Changed
+### Removed
 - Remove mutable object, leave only immutable.
 - Remove implementation of Serializable interface.
 

README.md

@@ -6,19 +6,140 @@
 [![Coverage Status][ico-scrutinizer]][link-scrutinizer]
 [![Quality Score][ico-code-quality]][link-code-quality]
 
-*TBD* 
+Implementation of the **Date Range** missing in PHP.
 
 ## Install
 
-Via [Composer](https://getcomposer.org)
+Using [Composer](https://getcomposer.org)
 
 ```bash
 composer require z-ee/date-range
 ```
 
 ## Usage
 
-*TBD*
+### DateRange - value object
+
+Instantiating value object and accessing properties:
+
+~~~php
+$range = new DateRange(new DateTime('-1 day'), new DateTime('+1 day'));
+// Checking if range has start date
+$range->hasStartDate();
+// Accessing range start date
+$range->getStartDate()->format('c');
+// Checking if range has end date
+$range->hasEndDate();
+// Accessing range end date
+$range->getEndDate()->format('c');
+// Checking if range is finite
+$range->isFinite();
+// Checking if range already started
+$range->isStarted();
+// Checking if range already ended
+$range->isEnded();
+// Checking if range started on specific date
+$range->isStartedOn(new DateTime());
+// Checking if range ended on specific date
+$range->isEndedOn(new DateTime());
+// Accessing range interval
+$range->getDateInterval()->format('%s');
+// Printing
+echo $range;
+// Representing as JSON
+json_encode($range);
+~~~
+
+Iterating over the range:
+
+~~~php
+$range = new DateRange(new DateTime('-1 day'), new DateTime('+1 day'));
+
+foreach ($range->getDatePeriod(new DateInterval('P1D')) as $date) {
+    echo $date->format('Y-m-d');
+}
+~~~
+
+Splitting range into smaller ranges:
+
+~~~php
+$range = new DateRange(new DateTime('-1 day'), new DateTime('+1 day'));
+
+foreach ($range->split(new DateInterval('P1D')) as $range) {
+    echo $range;
+}
+~~~
+
+Date range is immutable, any changes resulting to new object:
+
+~~~php
+$initial = new DateRange(new DateTime('-1 day'), new DateTime('+1 day'));
+$actual = $initial->setStartDate(new DateTime('now'));
+if ($initial === $actual) {
+    throw new LogicException('Oh, ah');
+}
+~~~
+
+### DateRangeProvider - the date ranges builder.
+
+Using builder to create new range with specific rules:
+
+~~~php
+class RangeForYear implements DateRangeProvider
+{
+    /**
+     * @var int
+     */
+    private $year;
+
+    /**
+     * @param int $year
+     */
+    public function __construct(int $year)
+    {
+        $this->year = $year;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getDateRange(): DateRangeInterface
+    {
+        return new DateRange(
+            new DateTimeImmutable(DateTimeImmutable::createFromFormat('c', "{$this->year}-01-01T00:00:00Z")),
+            new DateTimeImmutable(DateTimeImmutable::createFromFormat('c', "{$this->year}-12-31T23:59:59Z"))
+        );
+    }
+~~~
+
+Your classes might depend on range provider instead of `DateRange`,
+useful when predefined ranges are more meaningful than range interface:
+
+~~~php
+class ReportCalculator
+{
+    public function calculate(DateRangeProvider $provider)
+    {
+        echo $provider->getDateRange();
+    }
+}
+
+$calculator->calculate(new RangeForYear(2017));
+$calculator->calculate(new RangeForQuarter(2017));
+$calculator->calculate(new RangeForMonth(2017));
+~~~
+
+Even your class might require concrete range contact:
+
+~~~php
+class ReportCalculator
+{
+    public function calculate(FiniteDateRangeProvider $provider)
+    {
+        echo $provider->getDateRange();
+    }
+}
+~~~
 
 ## Testing