API Reference

Range

Piwik\Period\

Range

Arbitrary date range representation.

This class represents a period that contains a list of consecutive days as subperiods It is created when the period query parameter is set to range and is used to calculate the subperiods of multiple period requests (eg, when period=day and date=2007-07-24,2013-11-15).

The range period differs from other periods mainly in that since it is arbitrary, range periods are not pre-archived by the cron core:archive command.

Methods

The 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 start date of the period.

Signature

  • It returns a Date value.
  • It throws one of the following exceptions:

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 end date 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 the current period as a string.

Signature

  • It returns a string value.

getLocalizedShortString()

Returns the current period as a localized short string.

Signature

  • It returns a string value.

getLocalizedLongString()

Returns the current period as a localized long string.

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

__construct()

Constructor.

Signature

  • It accepts the following parameter(s):
    • $strPeriod (string) — The type of period each subperiod is. Either 'day', 'week', 'month' or 'year'.
    • $strDate (string) — The date range, eg, '2007-07-24,2013-11-15'.
    • $timezone (string) — The timezone to use, eg, 'UTC'.
    • $today (bool|Date) — The date to use as today. Defaults to Date::factory('today', $timzeone).

setDefaultEndDate()

Sets the default end date of the period.

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

parseDateRange()

Given a date string, returns false if not a date range, or returns the array containing start and end dates.

Signature

  • It accepts the following parameter(s):

    • $dateString (string) —

  • Returns: mixed — array(1 => dateStartString, 2 => dateEndString) or false if the input was not a date range.

getLastDate()

Returns the date that is one period before the supplied date.

Signature

  • It accepts the following parameter(s):

    • $date (bool|string) — The date to get the last date of.
    • $period (bool|string) — The period to use (either 'day', 'week', 'month', 'year');

  • Returns: array — An array with two elements, a string for the date before $date and a Period instance for the period before $date.

getDateXPeriodsAgo()

Returns the date that is X periods before the supplied date.

Signature

  • It accepts the following parameter(s):

    • $subXPeriods

    • $date

    • $period

  • Returns: array — An array with two elements, a string for the date before $date and a Period instance for the period before $date.

getDayCount()

Return the number of days contained in this range

Signature

  • It returns a int value.
  • It throws one of the following exceptions:

getRelativeToEndDate()

Returns a date range string given a period type, end date and number of periods the range spans over.

Signature

  • It accepts the following parameter(s):

    • $period (string) — The sub period type, 'day', 'week', 'month' and 'year'.
    • $lastN (int) — The number of periods of type $period that the result range should span.
    • $endDate (string) — The desired end date of the range.
    • $site (Site) — The site whose timezone should be used.

  • Returns: string — The date range string, eg, '2012-01-02,2013-01-02'.

getImmediateChildPeriodLabel()

Signature

  • It does not return anything or a mixed result.

getParentPeriodLabel()

Signature

  • It does not return anything or a mixed result.

getMaxAllowedEndTimestamp()

Returns the max allowed end timestamp for a range. If an enddate after this timestamp is provided, Matomo will automatically lower the end date to the date returned by this method.

The max supported timestamp is always set to end of the current year plus 10 years.

Signature

  • It returns a int value.