PHP Class League\Period\Period

Since: 1.0.0
Author: Ignace Nyamagana Butera ([email protected])
Inheritance: implements JsonSerializabl\JsonSerializable
Show file Open project: thephpleague/period Class Usage Examples

Protected Properties

Property Type Description
$endDate DateTimeImmutable Period ending excluded date point.
$startDate DateTimeImmutable Period starting included date point.

Public Methods

Method Description
__construct ( DateTimeInterfac\DateTimeInterface | string $startDate, DateTimeInterfac\DateTimeInterface | string $endDate ) Create a new instance.
__set_state ( array $period )
__toString ( ) : string String representation of a Period using ISO8601 Time interval format
abuts ( Period $period ) : boolean Tells whether two Period object abuts
add ( DateInterva\DateInterval | integer | string $interval ) : static Returns a new Period object with an added interval
compareDuration ( Period $period ) : integer Compares two Period objects according to their duration.
contains ( Period | DateTimeInterfac\DateTimeInterface | string $index ) : boolean Tells whether the specified index is fully contained within the current Period object.
createFromDay ( DateTimeInterfac\DateTimeInterface | string $day ) : static Create a Period object for a specific day
createFromDuration ( DateTimeInterfac\DateTimeInterface | string $startDate, mixed $interval ) : static Create a Period object from a starting point and an interval.
createFromDurationBeforeEnd ( DateTimeInterfac\DateTimeInterface | string $endDate, mixed $interval ) : static Create a Period object from a ending datepoint and an interval.
createFromMonth ( integer $year, integer $month ) : static Create a Period object for a specific month
createFromQuarter ( integer $year, integer $quarter ) : static Create a Period object for a specific quarter
createFromSemester ( integer $year, integer $semester ) : static Create a Period object for a specific semester
createFromWeek ( integer $year, integer $week ) : static Create a Period object for a specific week
createFromYear ( integer $year ) : static Create a Period object for a specific Year
dateIntervalDiff ( Period $period ) : DateInterval Returns the difference between two Period objects expressed in \DateInterval
diff ( Period $period ) : Period[] Computes the difference between two overlapsing Period objects
durationGreaterThan ( Period $period ) : boolean Tells whether the current Period object duration is greater than the submitted one.
durationLessThan ( Period $period ) : boolean Tells whether the current Period object duration is less than the submitted one.
endingOn ( DateTimeInterfac\DateTimeInterface | string $endDate ) : static Returns a new Period object with a new ending date point.
gap ( Period $period ) : static Computes the gap between two Period objects.
getDateInterval ( ) : DateInterval Returns the Period duration as a DateInterval object.
getDatePeriod ( DateInterva\DateInterval | integer | string $interval, integer $option ) : DatePeriod Allows iteration over a set of dates and times, recurring at regular intervals, over the Period object.
getEndDate ( ) : DateTimeImmutable Returns the ending datepoint.
getStartDate ( ) : DateTimeImmutable Returns the starting date point.
getTimestampInterval ( ) : float Returns the Period duration as expressed in seconds
intersect ( Period $period ) : static Computes the intersection between two Period objects.
isAfter ( Period | DateTimeInterfac\DateTimeInterface | string $index ) : boolean Tells whether a Period is entirely after the specified index
isBefore ( Period | DateTimeInterfac\DateTimeInterface | string $index ) : boolean Tells whether a Period is entirely before the specified index
jsonSerialize ( ) : DateTim\DateTime[] implement JsonSerializable interface
merge ( Period $arg ) : static Merges one or more Period objects to return a new Period object.
move ( DateInterva\DateInterval | integer | string $interval ) : static Returns a new Period object where the datepoints are moved forwards or backward simultaneously by the given DateInterval
moveEndDate ( DateInterva\DateInterval | integer | string $interval ) : static Returns a new Period object with a new ending date point moved forward or backward by the given interval
moveStartDate ( DateInterva\DateInterval | integer | string $interval ) : static Returns a new Period object with a new starting date point moved forward or backward by the given interval
next ( DateInterva\DateInterval | integer | string $interval = null ) : static Returns a new Period object adjacent to the current Period and starting with its ending datepoint.
overlaps ( Period $period ) : boolean Tells whether two Period objects overlaps.
previous ( DateInterva\DateInterval | integer | string $interval = null ) : static Returns a new Period object adjacent to the current Period and ending with its starting datepoint.
sameDurationAs ( Period $period ) : boolean Tells whether the current Period object duration is equal to the submitted one
sameValueAs ( Period $period ) : boolean Tells whether two Period share the same datepoints.
split ( DateInterva\DateInterval | integer | string $interval ) : Generator Split a Period by a given interval
startingOn ( DateTimeInterfac\DateTimeInterface | string $startDate ) : static Returns a new Period object with a new included starting date point.
sub ( DateInterva\DateInterval | integer | string $interval ) : static Returns a new Period object with a Removed interval
timestampIntervalDiff ( Period $period ) : float Returns the difference between two Period objects expressed in seconds
withDuration ( DateInterva\DateInterval | integer | string $interval ) : static Returns a new Period object with a new ending date point.
withDurationBeforeEnd ( DateInterva\DateInterval | integer | string $interval ) : static Returns a new Period object with a new starting date point.

Protected Methods

Method Description
containsDatePoint ( DateTimeInterfac\DateTimeInterface | string $datepoint ) : boolean Tells whether a datepoint is fully contained within the current Period object.
containsPeriod ( Period $period ) : boolean Tells whether a Period object is fully contained within the current Period object.
convertDateTime ( DateTime $datetime ) : DateTimeImmutable Convert a DateTime object into a DateTimeImmutable object
createFromDatepoints ( DateTimeInterfac\DateTimeInterface | string $datePoint1, DateTimeInterfac\DateTimeInterface | string $datePoint2 ) : Period Create a new instance given two datepoints
createFromYearInterval ( integer $interval, integer $year, integer $index ) : static Create a Period object for a specific interval in a given year
filterDateInterval ( mixed $interval ) : DateInterval Validate a DateInterval.
filterDatePoint ( DateTimeInterfac\DateTimeInterface | string $datetime ) : DateTimeImmutable Validate a DateTime.
validateRange ( integer $value, integer $min, integer $max ) : integer Validate a int according to a range.
validateYear ( integer $year ) : integer Validate a year.

Method Details

__construct() public method

Create a new instance.
public __construct ( DateTimeInterfac\DateTimeInterface | string $startDate, DateTimeInterfac\DateTimeInterface | string $endDate )
$startDate DateTimeInterfac\DateTimeInterface | string starting date point
$endDate DateTimeInterfac\DateTimeInterface | string ending date point

__set_state() public static method

public static __set_state ( array $period )
$period array

__toString() public method

String representation of a Period using ISO8601 Time interval format
public __toString ( ) : string
return string

abuts() public method

Tells whether two Period object abuts
public abuts ( Period $period ) : boolean
$period Period
return boolean

add() public method

DEPRECATION WARNING! This method will be removed in the next major point release
Deprecation: deprecated since version 3.3.0 The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public add ( DateInterva\DateInterval | integer | string $interval ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

compareDuration() public method

Compares two Period objects according to their duration.
public compareDuration ( Period $period ) : integer
$period Period
return integer

contains() public method

Tells whether the specified index is fully contained within the current Period object.
public contains ( Period | DateTimeInterfac\DateTimeInterface | string $index ) : boolean
$index Period | DateTimeInterfac\DateTimeInterface | string
return boolean

containsDatePoint() protected method

Tells whether a datepoint is fully contained within the current Period object.
protected containsDatePoint ( DateTimeInterfac\DateTimeInterface | string $datepoint ) : boolean
$datepoint DateTimeInterfac\DateTimeInterface | string
return boolean

containsPeriod() protected method

Tells whether a Period object is fully contained within the current Period object.
protected containsPeriod ( Period $period ) : boolean
$period Period
return boolean

convertDateTime() protected static method

Convert a DateTime object into a DateTimeImmutable object
protected static convertDateTime ( DateTime $datetime ) : DateTimeImmutable
$datetime DateTime
return DateTimeImmutable

createFromDatepoints() protected static method

The datepoints will be used as to allow the creation of a Period object
protected static createFromDatepoints ( DateTimeInterfac\DateTimeInterface | string $datePoint1, DateTimeInterfac\DateTimeInterface | string $datePoint2 ) : Period
$datePoint1 DateTimeInterfac\DateTimeInterface | string datepoint
$datePoint2 DateTimeInterfac\DateTimeInterface | string datepoint
return Period

createFromDay() public static method

The date is truncated so that the Time range starts at midnight according to the date timezone. The duration is equivalent to one full day.
public static createFromDay ( DateTimeInterfac\DateTimeInterface | string $day ) : static
$day DateTimeInterfac\DateTimeInterface | string
return static

createFromDuration() public static method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public static createFromDuration ( DateTimeInterfac\DateTimeInterface | string $startDate, mixed $interval ) : static
$startDate DateTimeInterfac\DateTimeInterface | string The start date point
$interval mixed The interval
return static

createFromDurationBeforeEnd() public static method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public static createFromDurationBeforeEnd ( DateTimeInterfac\DateTimeInterface | string $endDate, mixed $interval ) : static
$endDate DateTimeInterfac\DateTimeInterface | string The start date point
$interval mixed The interval
return static

createFromMonth() public static method

Create a Period object for a specific month
public static createFromMonth ( integer $year, integer $month ) : static
$year integer
$month integer Month index from 1 to 12
return static

createFromQuarter() public static method

Create a Period object for a specific quarter
public static createFromQuarter ( integer $year, integer $quarter ) : static
$year integer
$quarter integer Quarter Index from 1 to 4
return static

createFromSemester() public static method

Create a Period object for a specific semester
public static createFromSemester ( integer $year, integer $semester ) : static
$year integer
$semester integer Semester Index from 1 to 2
return static

createFromWeek() public static method

Create a Period object for a specific week
public static createFromWeek ( integer $year, integer $week ) : static
$year integer
$week integer index from 1 to 53
return static

createFromYear() public static method

Create a Period object for a specific Year
public static createFromYear ( integer $year ) : static
$year integer
return static

createFromYearInterval() protected static method

Create a Period object for a specific interval in a given year
protected static createFromYearInterval ( integer $interval, integer $year, integer $index ) : static
$interval integer
$year integer
$index integer
return static

dateIntervalDiff() public method

Returns the difference between two Period objects expressed in \DateInterval
public dateIntervalDiff ( Period $period ) : DateInterval
$period Period
return DateInterval

diff() public method

Returns an array containing the difference expressed as Period objects The array will:
  • be empty if both objects have the same datepoints
  • contain one Period object if both objects share one datepoint
  • contain two Period objects if both objects share no datepoint
public diff ( Period $period ) : Period[]
$period Period
return Period[]

durationGreaterThan() public method

Tells whether the current Period object duration is greater than the submitted one.
public durationGreaterThan ( Period $period ) : boolean
$period Period
return boolean

durationLessThan() public method

Tells whether the current Period object duration is less than the submitted one.
public durationLessThan ( Period $period ) : boolean
$period Period
return boolean

endingOn() public method

Returns a new Period object with a new ending date point.
public endingOn ( DateTimeInterfac\DateTimeInterface | string $endDate ) : static
$endDate DateTimeInterfac\DateTimeInterface | string date point
return static

filterDateInterval() protected static method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
protected static filterDateInterval ( mixed $interval ) : DateInterval
$interval mixed The interval
return DateInterval

filterDatePoint() protected static method

Validate a DateTime.
protected static filterDatePoint ( DateTimeInterfac\DateTimeInterface | string $datetime ) : DateTimeImmutable
$datetime DateTimeInterfac\DateTimeInterface | string
return DateTimeImmutable

gap() public method

Computes the gap between two Period objects.
public gap ( Period $period ) : static
$period Period
return static

getDateInterval() public method

Returns the Period duration as a DateInterval object.
public getDateInterval ( ) : DateInterval
return DateInterval

getDatePeriod() public method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public getDatePeriod ( DateInterva\DateInterval | integer | string $interval, integer $option ) : DatePeriod
$interval DateInterva\DateInterval | integer | string The interval
$option integer can be set to DatePeriod::EXCLUDE_START_DATE to exclude the start date from the set of recurring dates within the period.
return DatePeriod

getEndDate() public method

Returns the ending datepoint.
public getEndDate ( ) : DateTimeImmutable
return DateTimeImmutable

getStartDate() public method

Returns the starting date point.
public getStartDate ( ) : DateTimeImmutable
return DateTimeImmutable

getTimestampInterval() public method

Returns the Period duration as expressed in seconds
public getTimestampInterval ( ) : float
return float

intersect() public method

Computes the intersection between two Period objects.
public intersect ( Period $period ) : static
$period Period
return static

isAfter() public method

Tells whether a Period is entirely after the specified index
public isAfter ( Period | DateTimeInterfac\DateTimeInterface | string $index ) : boolean
$index Period | DateTimeInterfac\DateTimeInterface | string
return boolean

isBefore() public method

Tells whether a Period is entirely before the specified index
public isBefore ( Period | DateTimeInterfac\DateTimeInterface | string $index ) : boolean
$index Period | DateTimeInterfac\DateTimeInterface | string
return boolean

jsonSerialize() public method

implement JsonSerializable interface
public jsonSerialize ( ) : DateTim\DateTime[]
return DateTim\DateTime[]

merge() public method

The resultant object represents the largest duration possible.
public merge ( Period $arg ) : static
$arg Period one or more Period objects
return static

move() public method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public move ( DateInterva\DateInterval | integer | string $interval ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

moveEndDate() public method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public moveEndDate ( DateInterva\DateInterval | integer | string $interval ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

moveStartDate() public method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public moveStartDate ( DateInterva\DateInterval | integer | string $interval ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

next() public method

If no duration is provided the new Period will be created using the current object duration The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public next ( DateInterva\DateInterval | integer | string $interval = null ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

overlaps() public method

Tells whether two Period objects overlaps.
public overlaps ( Period $period ) : boolean
$period Period
return boolean

previous() public method

If no duration is provided the new Period will have the same duration as the current one The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public previous ( DateInterva\DateInterval | integer | string $interval = null ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

sameDurationAs() public method

Tells whether the current Period object duration is equal to the submitted one
public sameDurationAs ( Period $period ) : boolean
$period Period
return boolean

sameValueAs() public method

Tells whether two Period share the same datepoints.
public sameValueAs ( Period $period ) : boolean
$period Period
return boolean

split() public method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public split ( DateInterva\DateInterval | integer | string $interval ) : Generator
$interval DateInterva\DateInterval | integer | string The interval
return Generator

startingOn() public method

Returns a new Period object with a new included starting date point.
public startingOn ( DateTimeInterfac\DateTimeInterface | string $startDate ) : static
$startDate DateTimeInterfac\DateTimeInterface | string date point
return static

sub() public method

DEPRECATION WARNING! This method will be removed in the next major point release
Deprecation: deprecated since version 3.3.0 The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public sub ( DateInterva\DateInterval | integer | string $interval ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

timestampIntervalDiff() public method

Returns the difference between two Period objects expressed in seconds
public timestampIntervalDiff ( Period $period ) : float
$period Period
return float

validateRange() protected static method

Validate a int according to a range.
protected static validateRange ( integer $value, integer $min, integer $max ) : integer
$value integer the value to validate
$min integer the minimum value
$max integer the maximal value
return integer

validateYear() protected static method

Validate a year.
protected static validateYear ( integer $year ) : integer
$year integer
return integer

withDuration() public method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public withDuration ( DateInterva\DateInterval | integer | string $interval ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

withDurationBeforeEnd() public method

The interval can be
  • a DateInterval object
  • an int interpreted as the duration expressed in seconds.
  • a string in a format supported by DateInterval::createFromDateString
public withDurationBeforeEnd ( DateInterva\DateInterval | integer | string $interval ) : static
$interval DateInterva\DateInterval | integer | string The interval
return static

Property Details

$endDate protected property

Period ending excluded date point.
protected DateTimeImmutable $endDate
return DateTimeImmutable

$startDate protected property

Period starting included date point.
protected DateTimeImmutable $startDate
return DateTimeImmutable