API Reference

Period

Piwik\

Period

Date range representation.

Matomo (formerly Piwik) allows users to view aggregated statistics for single days and for date ranges consisting of several days. When requesting data, a date string and a period string must be used to specify the date range that the data regards. This is the class Matomo uses to represent and manipulate those date ranges.

There are five types of periods in Matomo: day, week, month, year and range, where range is any date range. The reason the other periods exist instead of just range is that Matomo will pre-archive reports for days, weeks, months and years, while every custom date range is archived on-demand.

Methods

The abstract class defines the following methods:

__sleep()

Signature

  • It does not return anything or a mixed result.

__wakeup()

Signature

  • It does not return anything or a mixed result.

isMultiplePeriod()

Returns true if $dateString and $period represent multiple periods.

Will return true for date/period combinations where date references multiple dates and period is not 'range'. For example, will return true for:

  • date = 2012-01-01,2012-02-01 and period = 'day'
  • date = 2012-01-01,2012-02-01 and period = 'week'
  • date = last7 and period = 'month'

etc.

Signature

  • It accepts the following parameter(s):
    • $dateString string The date query parameter value.
    • $period string The period query parameter value.
  • It returns a boolean value.

checkDateFormat()

Checks the given date format whether it is a correct date format and if not, throw an exception.

For valid date formats have a look at the Date::factory() method and isMultiplePeriod() method.

Signature

  • It accepts the following parameter(s):

    • $dateString (string) —

  • It does not return anything or a mixed result.

  • It throws one of the following exceptions:
    • Exception — If $dateString is in an invalid format or if the time is before Tue, 06 Aug 1991.

getDateStart()

Returns the first day of the period.

Signature

  • It returns a Date value.

getDateTimeStart()

Returns the start date & time of this period.

Signature

  • It returns a Date value.

getDateTimeEnd()

Returns the end date & time of this period.

Signature

  • It returns a Date value.

getDateEnd()

Returns the last day of the period.

Signature

  • It returns a Date value.

getId()

Returns the period ID.

Signature

  • Returns: int — A unique integer for this type of period.

getLabel()

Returns the label for the current period.

Signature

  • Returns: string — "day", "week", "month", "year", "range"

getNumberOfSubperiods()

Returns the number of available subperiods.

Signature

  • It returns a int value.

getSubperiods()

Returns the set of Period instances that together make up this period. For a year, this would be 12 months. For a month this would be 28-31 days. Etc.

Signature

isDateInPeriod()

Returns whether the date $date is within the current period or not.

Note: the time component of the period's dates and $date is ignored.

Signature

  • It accepts the following parameter(s):

  • It returns a bool value.

isPeriodIntersectingWith()

Returns whether the given period date range intersects with this one.

Signature

  • It accepts the following parameter(s):

  • It returns a bool value.

getBoundsInTimezone()

Returns the start day and day after the end day for this period in the given timezone.

Signature

  • It accepts the following parameter(s):

    • $timezone (string) —

  • It does not return anything or a mixed result.

toString()

Returns a list of strings representing the current period.

Signature

  • It accepts the following parameter(s):

    • $format (string) — The format of each individual day.

  • Returns: array|string — An array of string dates that this period consists of.

__toString()

See toString().

Signature

  • It returns a string value.

getPrettyString()

Returns a pretty string describing this period.

Signature

  • It returns a string value.

getLocalizedShortString()

Returns a short string description of this period that is localized with the currently used language.

Signature

  • It returns a string value.

getLocalizedLongString()

Returns a long string description of this period that is localized with the currently used language.

Signature

  • It returns a string value.

getRangeString()

Returns the date range string comprising two dates

Signature

  • Returns: string — eg, '2012-01-01,2012-01-31'.