Period

Upgrading from 3.x to 4.x

4.0 is a new major version that comes with backward compatibility breaks.

This guide will help you migrate from a 3.x version to 4.0. It will only explain backward compatibility breaks, it will not present the new features (read the documentation for that).

Installation

If you are using composer then you should update the require section of your composer.json file.

composer require league/period:^4.0

This will edit (or create) your composer.json file.

PHP version requirement

4.0 requires a PHP version greater than or equal 7.1.3 (was previously 5.5.9).

HHVM support is dropped.

Removed methods

Already deprecated methods

The following methods were already marked as deprecated is the 3.x line. They are now removed from the class.

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.

removed named constructors new functions
Period::createFromYear year
Period::createFromMonth month
Period::createFromWeek iso_week
Period::createFromDay day
Period::createFromSemester semester
Period::createFromQuarter quarter
Period::createFromDuration interval_after
Period::createFromDurationBeforeEnd interval_before

The functions take the same arguments in the same order.

Before:

use League\Period\Period;

$period = Period::createFromDuration('2014-03-01', '1 MONTH');

After:

use function League\Period\interval_after;

$period = interval_after('2014-03-01', '1 MONTH');

Renamed methods

To remove ambiguity, the following methods have been renamed

previous name new name
Period::sameValueAs Period::equals
Period::sameDurationAs Period::durationEquals
Period::compareDuration Period::durationCompare
Period::withDuration Period::withDurationAfterStart

Before:

$period = Period::createFromDuration('2014-03-01', '1 MONTH');
$alt_period = $period->withDuration('1 WEEK');

After:

$period = interval_after('2014-03-01', '1 MONTH');
$alt_period = $period->withDurationAfterStart('1 WEEK');

Backward Incompatible Changes

Period::contains

To be more consistent with the mathematical representation of right open intervals, the following snippets differs between version 3.x et version 4.

Before:

$instant = new Period('2014-03-01', '2014-03-01');
$period->contains($instant->getStartDate()); //return true
$period->contains($instant->getEndDate()); //return false

After:

$instant = new Period('2014-03-01', '2014-03-01');
$period->contains($instant->getStartDate()); //return false
$period->contains($instant->getEndDate());   //return false

In other words, starting with version 4.0, an interval whose duration is equivalent to new DateInterval('PT0S') can not contains any datepoint.

Period::diff

The methods now always returns an array containing two values. Those values can be a Period object or null.

Before:

$period = Period::createFromDuration('2014-03-01', '1 MONTH');
$alt_period = Period::createFromDuration('2014-03-01', '2 WEEKS');

$diff = $period->diff($alt_period);
count($diff); //returns 1
get_class($diff[0]); //returns League\Period\Period

After:

$period = interval_after('2014-03-01', '1 MONTH');
$alt_period = interval_after('2014-03-01', '2 WEEKS');

$diff = $period->diff($alt_period);
count($diff); //returns 2
get_class($diff[0]); //returns League\Period\Period
is_null($diff[1]);  //returns true

Period::jsonSerialize

The output from Period::jsonSerialize has been updated to enable a better translation between the PHP and the Javascript DateTime notation.

Before:

date_default_timezone_set('Africa/Kinshasa');

use League\Period\Period;

$period = new Period('2014-05-01 00:00:00', '2014-05-08 00:00:00');

$res = json_decode(json_encode($period), true);
//  $res will be equivalent to:
// [
//      'startDate' => [
//          'date' => '2014-05-01 00:00:00',
//          'timezone_type' => 3,
//          'timezone' => 'Africa/Kinshasa',
//      ],
//      'endDate' => [
//          'date' => '2014-05-08 00:00:00',
//          'timezone_type' => 3,
//          'timezone' => 'Africa/Kinshasa',
//      ],
// ]

After:

date_default_timezone_set('Africa/Kinshasa');

$period = new Period('2014-05-01 00:00:00', '2014-05-08 00:00:00');

$res = json_decode(json_encode($period), true);
//  $res will be equivalent to:
// [
//      'startDate' => '2014-04-30T23:00:00.000000Z,
//      'endDate' => '2014-05-07T23:00:00.000000Z',
// ]