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();