Period

This is the documentation for the unsupported version 3.0. 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.

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

Using datepoints

Period::startingOn

Description

<?php

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

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

Example

<?php

use League\Period\Period;

$period    = Period::createFromMonth(2014, 3);
$newPeriod = $period->startingOn('2014-02-01');
$period->getStartDate(); //returns DateTimeImmutable('2014-03-01');
$newPeriod->getStartDate(); //returns DateTimeImmutable('2014-02-01');
// $period->getEndDate() equals $newPeriod->getEndDate();

Period::endingOn

Description

<?php

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

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

Example

<?php

use League\Period\Period;

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

Using durations

Period::withDuration

Description

<?php

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

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

Example

<?php

use League\Period\Period;

$period    = Period::createFromMonth(2014, 3);
$newPeriod = $period->withDuration('2 WEEKS');
$period->getEndDate();    //returns DateTimeImmutable('2014-04-01');
$newPeriod->getEndDate(); //returns DateTimeImmutable('2014-03-16');
// $period->getStartDate() equals $newPeriod->getStartDate();

Period::withDurationBeforeEnd

This method is introduced in version 3.4.0

Description

<?php

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

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

Example

<?php

use League\Period\Period;

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

Period::move

This method is introduced in version 3.3.0

Description

<?php

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

<?php

use League\Period\Period;

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

Period::moveStartDate

This method is introduced in version 3.3.0

Description

<?php

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

<?php

use League\Period\Period;

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

Period::moveEndDate

This method is introduced in version 3.3.0

Description

<?php

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

<?php

use League\Period\Period;

$period = Period::createFromMonth(2014, 3);
$newPeriod = $period->moveEndtDate('1 MONTH');
$period->getStartDate()     //returns DateTimeImmutable('2014-03-01');
$period->getEndDate();      //returns DateTimeImmutable('2014-04-01');
$newPeriod->getStartDate(); //returns DateTimeImmutable('2014-03-01');
$newPeriod->getEndDate();   //returns DateTimeImmutable('2014-05-01');

Period::add

This method is deprecated since version 3.3.0 and will be remove in the next major release. You should update your code to use Period::moveEndDate with a positive interval.

Description

<?php

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

Returns a new Period object by adding an interval to the current ending excluded datepoint.

Example

<?php

use League\Period\Period;

$period    = Period::createFromMonth(2014, 3);
$newPeriod = $period->add('2 WEEKS');
// $period->getStartDate() equals $newPeriod->getStartDate();

Period::sub

This method is deprecated since version 3.3.0 and will be remove in the next major release. You should update your code to use Period::moveEndDate with a negative interval.

Description

<?php

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

Returns a new Period object by substracting an interval to the current ending excluded datepoint.

Example

<?php

use League\Period\Period;

$period    = Period::createFromMonth(2014, 3);
$newPeriod = $period->sub('2 WEEKS');
// $period->getStartDate() equals $newPeriod->getStartDate();

Period::next

Description

<?php

public Period::next(mixed $duration = null): Period

Returns a new Period object adjacent to the current Period and starting with its ending datepoint.

Parameter

If no interval is provided, the new Period object will be created using the current Period duration.

Example

<?php

use League\Period\Period;

$period    = Period::createFromMonth(2014, 3);
$newPeriod = $period->next('1 MONTH');
// $period->getEndDate() equals $newPeriod->getStartDate();

When no $duration is provided to the method the new Period duration may vary. See below for a concrete example

<?php

use League\Period\Period;

$january  = Period::createFromMonth(2012, 1); //January 2012
$february = $period->next();
$march    = $newPeriod->next();
$january->sameDurationAs($february); //return false;
$january->sameDurationAs($march);    //return false;

echo $january;  // 2012-01-01T00:00:00+0100/2012-02-01T00:00:00+0100
echo $february; // 2012-02-01T00:00:00+0100/2012-03-01T00:00:00+0100
echo $march;    // 2012-03-01T00:00:00+0100/2012-03-30T00:00:00+0200

// $march does not represents the full month
// since the ending datepoint is excluded from the period!!

To remove any ambiguity, it is recommended to always provide a $duration when using Period::next

Period::previous

Description

<?php

public Period::previous(mixed $duration = null): Period

Complementary to Period::next, the created Period object is adjacent to the current Period but its ending datepoint is equal to the starting datepoint of the current object.

Example

<?php

use League\Period\Period;

$period    = Period::createFromMonth(2014, 3);
$newPeriod = $period->previous('1 WEEK');
// $period->getEndDate() equals $newPeriod->Start();
$period->durationGreaterThan($newPeriod); //return true

The method must be used with the same arguments and warnings as Period::next.

Period::next and Period::previous methods allow to easily create adjacent Periods as shown in the graph below

<?php

use League\Period\Period;

$current = Period::createFromMonth(2012, 1);
$prev    = $current->previous('1 MONTH');
$next    = $curent->next('1 MONTH');

Using another Period object

Period::merge

Description

<?php

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

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

Example

<?php

use League\Period\Period;

$period = Period::createFromSemester(2012, 1);
$alt    = Period::createFromWeek(2013, 4);
$other  = Period::createFromDuration('2012-03-07 08:10:27', 86000*3);
$newPeriod = $period->merge($alt, $other);
// $newPeriod->getStartDate() equals $period->getStartDate();
// $newPeriod->getEndDate() equals $altPeriod->getEndDate();