This is the documentation for version 4.0 which will be supported until 2022-08-21. Please consider upgrading your code to the latest stable version

Modifying Period objects

You can manipulate a Period object according to their datepoints or durations.

Period is an immutable value object which means that any change returns a new Period object.

datepoint and duration conversions are done internally using the League\Period\Datepoint and the League\Period\Duration classes.

If no Period object can be created the modifying methods throw a Period\Exception exception.

Using datepoints

Period::startingOn

public Period::startingOn(mixed $datepoint): Period

Returns a new Period object with $datepoint as the new starting datepoint.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->startingOn('2014-02-01');
$interval->getStartDate(); //returns DateTimeImmutable('2014-03-01');
$new_interval->getStartDate(); //returns DateTimeImmutable('2014-02-01');
// $interval->getEndDate() equals $new_interval->getEndDate();

Period::endingOn

public Period::endingOn(mixed $datepoint): Period

Returns a new Period object with $datepoint as the new ending datepoint.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->EndingOn('2014-03-16');
$interval->getEndDate(); //returns DateTimeImmutable('2014-04-01');
$new_interval->getEndDate(); //returns DateTimeImmutable('2014-03-16');
// $interval->getStartDate() equals $new_interval->getStartDate();

Using durations

Period::withDurationAfterStart

public Period::withDurationAfterStart(mixed $duration): Period

Returns a new Period object by updating its duration. Only the ending datepoint is updated.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->withDurationAfterStart('2 WEEKS');
$interval->getEndDate();    //returns DateTimeImmutable('2014-04-01');
$new_interval->getEndDate(); //returns DateTimeImmutable('2014-03-16');
// $interval->getStartDate() equals $new_interval->getStartDate();

Period::withDurationBeforeEnd

public Period::withDurationBeforeEnd(mixed $duration): Period

Returns a new Period object by updating its duration. Only the starting datepoint is updated.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->withDurationBeforeEnd('2 DAYS');
$interval->getStartDate();    //returns DateTimeImmutable('2014-03-01');
$new_interval->getStartDate(); //returns DateTimeImmutable('2014-03-30');
// $interval->getEndDate() equals $new_interval->getEndDate();

Period::move

public Period::move(mixed $duration): Period

Returns a new Period object where the endpoints are moved forward or backward simultaneously by a given interval.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->move('1 MONTH');
$interval->getStartDate()     //returns DateTimeImmutable('2014-03-01');
$interval->getEndDate();      //returns DateTimeImmutable('2014-04-01');
$new_interval->getStartDate(); //returns DateTimeImmutable('2014-04-01');
$new_interval->getEndDate();   //returns DateTimeImmutable('2014-05-01');

Period::moveStartDate

public Period::moveStartDate(mixed $duration): Period

Returns a new Period object where the starting endpoint is moved forward or backward by a given interval.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->moveStartDate('-1 MONTH');
$interval->getStartDate()     //returns DateTimeImmutable('2014-03-01');
$interval->getEndDate();      //returns DateTimeImmutable('2014-04-01');
$new_interval->getStartDate(); //returns DateTimeImmutable('2014-02-01');
$new_interval->getEndDate();   //returns DateTimeImmutable('2014-04-01');

Period::moveEndDate

public Period::moveEndDate(mixed $duration): Period

Returns a new Period object where the ending endpoint is moved forward or backward by a given interval.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->moveEndDate('1 MONTH');
$interval->getStartDate()     //returns DateTimeImmutable('2014-03-01');
$interval->getEndDate();      //returns DateTimeImmutable('2014-04-01');
$new_interval->getStartDate(); //returns DateTimeImmutable('2014-03-01');
$new_interval->getEndDate();   //returns DateTimeImmutable('2014-05-01');

Period::expand

public Period::expand(mixed $duration): Period

Returns a new Period object where the given interval is:

subtracted from the starting endpoint
added to the ending endpoint

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->expand('1 MONTH');
$interval->getStartDate()     //returns DateTimeImmutable('2014-03-01');
$interval->getEndDate();      //returns DateTimeImmutable('2014-04-01');
$new_interval->getStartDate(); //returns DateTimeImmutable('2014-02-01');
$new_interval->getEndDate();   //returns DateTimeImmutable('2014-05-01');

If you need to shrink the time range you can simply use a inverted DateInterval object

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->expand('-1 DAY');
$interval->getStartDate();     //returns DateTimeImmutable('2014-03-01');
$interval->getEndDate();      //returns DateTimeImmutable('2014-04-01');
$new_interval->getStartDate(); //returns DateTimeImmutable('2014-03-02');
$new_interval->getEndDate();   //returns DateTimeImmutable('2014-03-31');

Using the boundary information

Period::withBoundaryType

Since version 4.4

public Period::withBoundaryType(string $boundaryType): Period

Returns a new Period object with a different boundary type.

Example

$interval = Period::fromMonth(2014, 3);
$new_interval = $interval->withBoundaryType(Period::INCLUDE_ALL);
$interval->format('Y-m-d'); // '[2014-03-01, 2014-04-01)'
$new_interval->format('Y-m-d'); // '[2014-03-01, 2014-04-01]'

Using another Period object

Period::merge

public Period::merge(Period ...$intervals): Period

Merges two or more Period objects by returning a new Period object which englobes all the submitted objects.

Example

$interval = Period::fromSemester(2012, 1);
$alt = Period::fromIsoWeek(2013, 4);
$other = Period::after('2012-03-07 08:10:27', 86000*3);
$merge_interval = $interval->merge($alt, $other);
// $merge_interval->getStartDate() equals $period->getStartDate();
// $merge_interval->getEndDate() equals $altPeriod->getEndDate();

Since version 4.8 this method when used with no argument returns the current instance unchanged, previously it would trigger a TypeError.