Period

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 functions.

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 included datepoint.

Example

$interval = month(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 excluded datepoint.

Example

$interval = month(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 excluded ending datepoint is updated.

Example

$interval = month(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 included starting datepoint is updated.

Example

$interval = month(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 = month(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 = month(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 = month(2014, 3);
$new_interval = $interval->moveEndtDate('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:

Example

$interval = month(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 = month(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 another Period object

Period::merge

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

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

Example

$interval = semester(2012, 1);
$alt = iso_week(2013, 4);
$other = interval_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();