Update documentation before release

README.md

@@ -8,16 +8,16 @@ Period
 [![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/thephpleague/period.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/period/code-structure)
 [![Total Downloads](https://img.shields.io/packagist/dt/league/period.svg?style=flat-square)](https://packagist.org/packages/league/period)
 
-`Period` is PHP's missing time range API. It is based on [Resolving Feature Envy in the Domain](http://verraes.net/2014/08/resolving-feature-envy-in-the-domain/) by Mathias Verraes and extends the concept to cover all basic operations regarding time ranges.
+`Period` is PHP's missing time range API. Based on ideas from [Resolving Feature Envy in the Domain](http://verraes.net/2014/08/resolving-feature-envy-in-the-domain/) by Mathias Verraes, this package extends the concept to cover all basic operations regarding time ranges.
 
 ## Highlights
 
-- Treats a time range as an immutable value object
-- Exposes many named constructors to ease time range creation
+- Represents Interval, Datepoint, Duration and Collection as value objects
+- Exposes named constructors to ease object creation
 - Covers all basic manipulations related to time range
+- Enables working with simple or complex time ranges logic
 - Fully documented
 - Framework-agnostic
-- Composer ready, [PSR-2], and [PSR-4] compliant
 
 Documentation
 -------
@@ -38,6 +38,22 @@ Install `Period` using Composer.
 $ composer require league/period
 ```
 
+or download the library and:
+
+- use any other [PSR-4](http://www.php-fig.org/psr/psr-4/) compatible autoloader.
+- use the bundle autoloader script as shown below:
+
+~~~php
+require 'path/to/period/repo/autoload.php';
+
+use League\Period\Datepoint;
+
+Datepoint::create('2012-05-23')->getDay()->getDateInterval();
+//returns new DateInterval('P1D');
+~~~
+
+where `path/to/period/repo` represents the path where the library was extracted.
+
 Testing
 -------
 
@@ -68,9 +84,6 @@ Credits
 - [Ignace Nyamagana Butera](https://github.com/nyamsprod)
 - [All Contributors](https://github.com/thephpleague/period/graphs/contributors)
 
-[PSR-2]: http://www.php-fig.org/psr/psr-2/
-[PSR-4]: http://www.php-fig.org/psr/psr-4/
-
 License
 -------
 

docs/4.0/index.md

@@ -12,12 +12,14 @@ redirect_from: /examples/
 [![Build Status](//img.shields.io/travis/thephpleague/period/master.svg?style=flat-square)](//travis-ci.org/thephpleague/period)
 [![Total Downloads](//img.shields.io/packagist/dt/league/period.svg?style=flat-square)](//packagist.org/packages/league/period)
 
-`Period` is PHP's missing time range API. It is based on [Resolving Feature Envy in the Domain](//verraes.net/2014/08/resolving-feature-envy-in-the-domain/) by Mathias Verraes and extends the concept to cover all basic operations regarding interval.
+`Period` is PHP's missing time range API. Based on ideas from [Resolving Feature Envy in the Domain](http://verraes.net/2014/08/resolving-feature-envy-in-the-domain/) by Mathias Verraes, this package extends the concept to cover all basic operations regarding time ranges.
 
 <p class="message-info">In your code, you will always have to typehint against the <code>League\Period\Period</code> class directly because it is a immutable value object class marked as final and the library does not provide an interface.</p>
 
 <p class="message-info">Since <code>version 4.1</code> a <code>League\Period\Sequence</code> class is added to improve manipulating a collection of <code>Period</code> objects.</p>
 
+<p class="message-info">Since <code>version 4.4</code> the <code>Period</code> objects supports all types of boundary with the exception of unbounded interval.</p>
+
 ## Accessing the interval properties
 
 ~~~php
@@ -26,6 +28,7 @@ use League\Period\Period;
 $interval = new Period(
     new DateTime('2014-10-03 08:12:37'),
     new DateTimeImmutable('2014-10-03 08:12:37')
+    Period::INCLUDE_START_EXCLUDE_END
 );
 $start = $interval->getStartDate(); //returns a DateTimeImmutable
 $end = $interval->getEndDate();     //returns a DateTimeImmutable
@@ -51,13 +54,19 @@ To help easily instantiate your time range and manipulating it, the package come
 ## Comparing intervals
 
 ~~~php
-$interval = Period::after('2014-01-01', '1 WEEK');
-$alt_interval = Period::fromIsoWeek(2014, 1);
-$interval->durationEquals($alt_interval); //returns true
-$interval->equals($alt_interval);         //returns false
+$period = Period::after('2014-01-01', '1 MONTH', Period::INCLUDE_ALL);
+$altPeriod = Period::after('2014-01-01', '1 MONTH', Period::EXCLUDE_ALL);
+$period->durationEquals($altPeriod), //returns true
+$period->equals($altPeriod), //returns false
+$period->contains($altPeriod), //returns true
+$altPeriod->contains($period), //return false
+$period->contains('2014-01-10'), //returns true
+Datepoint::create('2014-02-10')->isDuring($period) //returns false
 ~~~
 
-The class comes with other ways to [compare time ranges](/4.0/comparing/) based on their duration and/or their datepoints.
+The class comes with other ways to [compare time ranges](/4.0/comparing/) based on their duration and/or their datepoints.  
+`Datepoint` extends `DateTimeImmutable` and offers more [methods](/4.0/datepoint/).
+
 
 ## Modifying interval
 

docs/4.0/upgrading.md

@@ -40,7 +40,40 @@ The following methods were already marked as deprecated is the `3.x` line. They
 
 ### Named constructors
 
-To reduce code and allow more flexibility all named constructors have been removed from the `Period` class. They are replaced by functions defined in the same namespace as the `Period` class.
+If you are migrating from `3.x` to `4.2+` version you should use the new named constructors
+
+| old named constructors                |  new named constructors |
+| ------------------------------------- | ----------------------- |
+| `Period::createFromYear`              | `Period::fromYear`      |
+| `Period::createFromMonth`             | `Period::fromMonth`     |
+| `Period::createFromWeek`              | `Period::fromIsoWeek`   |
+| `Period::createFromDay`               | `Period::fromDay`       |
+| `Period::createFromSemester`          | `Period::fromSemester`  |
+| `Period::createFromQuarter`           | `Period::fromQuarter`   |
+| `Period::createFromDuration`          | `Period::after`         |
+| `Period::createFromDurationBeforeEnd` | `Period::before`        |
+
+The arguments are the same as in version 3 but the new named constructors accepts overflow like `DateTimeImmutable` objects.
+
+Before:
+
+~~~php
+use League\Period\Period;
+
+$period = Period::createFromMonth(2013, 15);
+// throw LogicException
+~~~
+
+After:
+
+~~~php
+use League\Period\Period;
+
+$period = Period::fromMonth(2013, 15);
+// returns new Period('2014-03-01', '2014-04-01')
+~~~
+
+If you are using `4.2-` version you are required to use functions defined in the same namespace as the `Period` class.
 
 | removed named constructors            |  new functions    |
 | ------------------------------------- | ----------------- |

docs/_data/project.yml

@@ -25,11 +25,11 @@ author:
     name: 'Ignace Nyamagana Butera'
     twitter_account: 'nyamsprod'
 highlights:
-    description: "<code>Period</code> is PHP's Time Range class. It is based on <a href=\"http://verraes.net/2014/08/resolving-feature-envy-in-the-domain/\">Resolving Feature Envy in the Domain</a> by Mathias Verraes and extends the concept to cover all basic operations regarding time ranges."
+    description: "<code>Period</code> is PHP's Time Range class. Based on ideas from <a href=\"http://verraes.net/2014/08/resolving-feature-envy-in-the-domain/\">Resolving Feature Envy in the Domain</a> by Mathias Verraes, this package extends the concept to cover all basic operations regarding time ranges."
     features:
-        - Treats date and time range as immutable value objects
-        - Exposes named constructors to ease time range creation
+        - Uses Immutable Value Objects
+        - Uses named constructors to ease object creation
         - Covers all basic manipulations related to time range
-        - Framework-agnostic
+        - Enables working with simple or complex time ranges logic
 composer: '$ composer require league/period'
 support: 'Once a new major version is released, the previous stable release remains supported for six more months through patches and security fixes.'

docs/index.md

@@ -21,7 +21,7 @@ $endDate = $date->add($duration);
 $interval = new Period($startDate, $endDate);
 ~~~
 
-To help you start working with `Period` objects, the library comes bundled with many more named constructors to ease manipulating datetime intervals.
+To help you start working with `Period` objects, the library comes bundled with many more named constructors to ease datepoint, duration and intervals creation.
 
 ## iterating over the interval made simple
 
@@ -47,15 +47,17 @@ The library also allow iterating backwards over the interval.
 
 ## compare intervals and datepoints
 
-You can compare time ranges based on their duration and/or their datepoints.
+You can compare time ranges based on their duration, their datepoints and even their boundary types.
 
 ~~~php
-$period = Period::after('2014-01-01', '1 WEEK');
-$altPeriod = Period::fromIsoWeek(2014, 3);
-$period->durationEquals($altPeriod); //returns true
-$period->equals($altPeriod); //returns false
-$period->contains($altPeriod); //returns false
-$period->contains('2014-01-02'); //returns true
+$period = Period::after('2014-01-01', '1 MONTH', Period::INCLUDE_ALL);
+$altPeriod = Period::after('2014-01-01', '1 MONTH', Period::EXCLUDE_ALL);
+$period->durationEquals($altPeriod), //returns true
+$period->equals($altPeriod), //returns false
+$period->contains($altPeriod), //returns true
+$altPeriod->contains($period), //return false
+$period->contains('2014-01-10'), //returns true
+Datepoint::create('2014-02-10')->isDuring($period) //returns false
 ~~~
 
 ## Modifying time ranges
@@ -74,7 +76,7 @@ $altPeriod->durationGreaterThan($period); //return true;
 Format and export your `Period` instance following standardized format.
 
 ~~~php
-$period = Period::after('2014-10-03 08:00:00', 3600);
+$period = Period::after('2014-10-03 08:00:00', 3600, Period::INCLUDE_START_EXCLUDE_END);
 
 echo $period; // 2014-10-03T06:00:00.000000Z/2014-10-03T07:00:00.000000Z
 echo $period->format('Y-m-d H:i:s'); // [2014-10-03 08:00:00, 2014-10-03 09:00:00)