API Reference

Date

Piwik\

Date

Utility class that wraps date/time related PHP functions.

Performance concerns

The helper methods in this class are instance methods and thus Date instances need to be constructed before they can be used. The memory allocation can result in noticeable performance degradation if you construct thousands of Date instances, say, in a loop.

Examples

Basic usage

$date = Date::factory('2007-07-24 14:04:24', 'EST');
$date->addHour(5);
echo $date->getLocalized("EEE, d. MMM y 'at' HH:mm:ss");

Properties

This class defines the following properties:

$now

Signature

  • Its type is not specified.

Methods

The class defines the following methods:

  • factory() — Creates a new Date instance using a string datetime value.
  • getDatetime() — Returns the current timestamp as a string with the following format: 'YYYY-MM-DD HH:MM:SS'.
  • getHourUTC() — Returns the current hour in UTC timezone.
  • getDateStartUTC()
  • getStartOfDay() — Returns the start of the day of the current timestamp in UTC.
  • getDateEndUTC()
  • getEndOfDay() — Returns the end of the day of the current timestamp in UTC.
  • setTimezone() — Returns a new date object with the same timestamp as $this but with a new timezone.
  • getUtcOffset() — Returns the offset to UTC time for the given timezone
  • adjustForTimezone() — Converts a timestamp from UTC to a timezone.
  • getDatetimeFromTimestamp() ash; Returns the date in the "Y-m-d H:i:s" PHP format
  • getTimestampUTC() — Returns the Unix timestamp of the date in UTC.
  • getTimestamp() — Returns the unix timestamp of the date in UTC, converted from the current timestamp timezone.
  • isLater() — Returns true if the current date is older than the given $date.
  • isEarlier() — Returns true if the current date is earlier than the given $date.
  • isLeapYear() — Returns true if the current year is a leap year, false otherwise.
  • toString() — Converts this date to the requested string format.
  • __toString() ash; See toString().
  • compareWeek() — Performs three-way comparison of the week of the current date against the given $date's week.
  • compareMonth() — Performs three-way comparison of the month of the current date against the given $date's month.
  • compareYear() — Performs three-way comparison of the month of the current date against the given $date's year.
  • isToday() — Returns true if current date is today.
  • now() ash; Returns a date object set to now in UTC (same as today(), except that the time is also set).
  • today() — Returns a date object set to today at midnight in UTC.
  • tomorrow() — Returns a date object set to tomorrow at midnight in UTC.
  • yesterday() — Returns a date object set to yesterday at midnight in UTC.
  • yesterdaySameTime() — Returns a date object set to yesterday with the current time of day in UTC.
  • lastWeek() — Returns a date object set to the day a week ago at midnight in UTC.
  • lastMonth() — Returns a date object set to the day a month ago at midnight in UTC.
  • lastYear() — Returns a date object set to the day a year ago at midnight in UTC.
  • setTime() — Returns a new Date instance with $this date's day and the specified new time of day.
  • setDay() — Returns a new Date instance with $this date's time of day and the day specified by $day.
  • setYear() — Returns a new Date instance with $this date's time of day, month and day, but with a new year (specified by $year).
  • subDay() — Subtracts $n number of days from $this date and returns a new Date object.
  • subWeek() — Subtracts $n weeks from $this date and returns a new Date object.
  • subMonth() — Subtracts $n months from $this date and returns the result as a new Date object.
  • subYear() — Subtracts $n years from $this date and returns the result as a new Date object.
  • getLocalized() — Returns a localized date string using the given template.
  • addDay() — Adds $n days to $this date and returns the result in a new Date.
  • addMonth() — Adds $n Month to $this date and returns the result in a new Date.
  • addHour() — Adds $n hours to $this date and returns the result in a new Date.
  • addHourTo() — Adds N number of hours to a UNIX timestamp and returns the result.
  • subHour() — Subtracts $n hours from $this date and returns the result in a new Date.
  • subSeconds() — Subtracts $n seconds from $this date and returns the result in a new Date.
  • addPeriod() — Adds a period to $this date and returns the result in a new Date instance.
  • subPeriod() — Subtracts a period from $this date and returns the result in a new Date instance.
  • secondsToDays() — Returns the number of days represented by a number of seconds.

factory()

Creates a new Date instance using a string datetime value. The timezone of the Date result will be in UTC.

Signature

  • It accepts the following parameter(s):
    • $dateString (string|int) — 'today', 'yesterday', 'now', 'yesterdaySameTime', a string with 'YYYY-MM-DD HH:MM:SS' format or a unix timestamp.
    • $timezone (string) — The timezone of the result. If specified, $dateString will be converted from UTC to this timezone before being used in the Date return value.
  • It returns a Date value.
  • 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.

getDatetime()

Returns the current timestamp as a string with the following format: 'YYYY-MM-DD HH:MM:SS'.

Signature

  • It returns a string value.

getHourUTC()

Returns the current hour in UTC timezone.

Signature

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

getDateStartUTC()

Signature

  • It returns a string value.

getStartOfDay()

Returns the start of the day of the current timestamp in UTC. For example, if the current timestamp is '2007-07-24 14:04:24' in UTC, the result will be '2007-07-24' as a Date.

Signature

  • It returns a Date value.

getDateEndUTC()

Signature

  • It returns a string value.

getEndOfDay()

Returns the end of the day of the current timestamp in UTC. For example, if the current timestamp is '2007-07-24 14:03:24' in UTC, the result will be '2007-07-24 23:59:59'.

Signature

  • It returns a Date value.

setTimezone()

Returns a new date object with the same timestamp as $this but with a new timezone.

See getTimestamp() to see how the timezone is used.

Signature

  • It accepts the following parameter(s):
    • $timezone (string) — eg, 'UTC', 'Europe/London', etc.
  • It returns a Date value.

getUtcOffset()

Returns the offset to UTC time for the given timezone

Signature

  • It accepts the following parameter(s):

    • $timezone (string) —

  • Returns: int — offset in seconds

adjustForTimezone()

Converts a timestamp from UTC to a timezone.

Signature

  • It accepts the following parameter(s):

    • $timestamp (int) — The UNIX timestamp to adjust.
    • $timezone (string) — The timezone to adjust to.

  • Returns: int — The adjusted time as seconds from EPOCH.

getDatetimeFromTimestamp()

Returns the date in the "Y-m-d H:i:s" PHP format

Signature

  • It accepts the following parameter(s):

    • $timestamp (int) —

  • It returns a string value.

getTimestampUTC()

Returns the Unix timestamp of the date in UTC.

Signature

  • It returns a int value.

getTimestamp()

Returns the unix timestamp of the date in UTC, converted from the current timestamp timezone.

Signature

  • It returns a int value.

isLater()

Returns true if the current date is older than the given $date.

Signature

  • It accepts the following parameter(s):

  • It returns a bool value.

isEarlier()

Returns true if the current date is earlier than the given $date.

Signature

  • It accepts the following parameter(s):

  • It returns a bool value.

isLeapYear()

Returns true if the current year is a leap year, false otherwise.

Signature

  • It returns a bool value.

toString()

Converts this date to the requested string format. See http://php.net/date for the list of format strings.

Signature

  • It accepts the following parameter(s):

    • $format (string) —

  • It returns a string value.

__toString()

See toString().

Signature

  • Returns: string — The current date in 'YYYY-MM-DD' format.

compareWeek()

Performs three-way comparison of the week of the current date against the given $date's week.

Signature

  • It accepts the following parameter(s):

  • Returns: int — Returns 0 if the current week is equal to $date's, -1 if the current week is earlier or 1 if the current week is later.

compareMonth()

Performs three-way comparison of the month of the current date against the given $date's month.

Signature

  • It accepts the following parameter(s):

    • $date (Date) — Month to compare

  • Returns: int — Returns 0 if the current month is equal to $date's, -1 if the current month is earlier or 1 if the current month is later.

compareYear()

Performs three-way comparison of the month of the current date against the given $date's year.

Signature

  • It accepts the following parameter(s):

    • $date (Date) — Year to compare

  • Returns: int — Returns 0 if the current year is equal to $date's, -1 if the current year is earlier or 1 if the current year is later.

isToday()

Returns true if current date is today.

Signature

  • It returns a bool value.

now()

Returns a date object set to now in UTC (same as today(), except that the time is also set).

Signature

  • It returns a Date value.

today()

Returns a date object set to today at midnight in UTC.

Signature

  • It returns a Date value.

tomorrow()

Returns a date object set to tomorrow at midnight in UTC.

Signature

  • It returns a Date value.

yesterday()

Returns a date object set to yesterday at midnight in UTC.

Signature

  • It returns a Date value.

yesterdaySameTime()

Returns a date object set to yesterday with the current time of day in UTC.

Signature

  • It returns a Date value.

lastWeek()

Returns a date object set to the day a week ago at midnight in UTC.

Signature

  • It returns a Date value.

lastMonth()

Returns a date object set to the day a month ago at midnight in UTC.

Signature

  • It returns a Date value.

lastYear()

Returns a date object set to the day a year ago at midnight in UTC.

Signature

  • It returns a Date value.

setTime()

Returns a new Date instance with $this date's day and the specified new time of day.

Signature

  • It accepts the following parameter(s):

    • $time (string) — String in the 'HH:MM:SS' format.

  • Returns: Date — The new date with the time of day changed.

setDay()

Returns a new Date instance with $this date's time of day and the day specified by $day.

Signature

  • It accepts the following parameter(s):
    • $day (int) — The day eg. 31.
  • It returns a Date value.

setYear()

Returns a new Date instance with $this date's time of day, month and day, but with a new year (specified by $year).

Signature

  • It accepts the following parameter(s):
    • $year (int) — The year, eg. 2010.
  • It returns a Date value.

subDay()

Subtracts $n number of days from $this date and returns a new Date object.

Signature

  • It accepts the following parameter(s):
    • $n (int) — An integer > 0.
  • It returns a Date value.

subWeek()

Subtracts $n weeks from $this date and returns a new Date object.

Signature

  • It accepts the following parameter(s):
    • $n (int) — An integer > 0.
  • It returns a Date value.

subMonth()

Subtracts $n months from $this date and returns the result as a new Date object.

Signature

  • It accepts the following parameter(s):

    • $n (int) — An integer > 0.

  • Returns: Date — new date

subYear()

Subtracts $n years from $this date and returns the result as a new Date object.

Signature

  • It accepts the following parameter(s):
    • $n (int) — An integer > 0.
  • It returns a Date value.

getLocalized()

Returns a localized date string using the given template.

The template should contain tags that will be replaced with localized date strings.

Signature

  • It accepts the following parameter(s):

    • $template (string) — eg. "MMM y"
    • $ucfirst (bool) — whether the first letter should be upper-cased

  • Returns: string — eg. "Aug 2009"

addDay()

Adds $n days to $this date and returns the result in a new Date.

instance.

Signature

  • It accepts the following parameter(s):
    • $n (int) — Number of days to add, must be > 0.
  • It returns a Date value.

addMonth()

Adds $n Month to $this date and returns the result in a new Date.

instance.

Signature

  • It accepts the following parameter(s):
    • $n (int) — Number of days to add, must be > 0.
  • It returns a Date value.

addHour()

Adds $n hours to $this date and returns the result in a new Date.

Signature

  • It accepts the following parameter(s):
    • $n (int) — Number of hours to add. Can be less than 0.
  • It returns a Date value.

addHourTo()

Adds N number of hours to a UNIX timestamp and returns the result. Using this static function instead of addHour() will be faster since a Date instance does not have to be created.

Signature

  • It accepts the following parameter(s):

    • $timestamp (int) — The timestamp to add to.
    • $n (Piwik\number) — Number of hours to add, must be > 0.

  • Returns: int — The result as a UNIX timestamp.

subHour()

Subtracts $n hours from $this date and returns the result in a new Date.

Signature

  • It accepts the following parameter(s):
    • $n (int) — Number of hours to subtract. Can be less than 0.
  • It returns a Date value.

subSeconds()

Subtracts $n seconds from $this date and returns the result in a new Date.

Signature

  • It accepts the following parameter(s):
    • $n (int) — Number of seconds to subtract. Can be less than 0.
  • It returns a Date value.

addPeriod()

Adds a period to $this date and returns the result in a new Date instance.

Signature

  • It accepts the following parameter(s):
    • $n (int) — The number of periods to add. Can be negative.
    • $period (string) — The type of period to add (YEAR, MONTH, WEEK, DAY, ...)
  • It returns a Date value.

subPeriod()

Subtracts a period from $this date and returns the result in a new Date instance.

Signature

  • It accepts the following parameter(s):
    • $n (int) — The number of periods to add. Can be negative.
    • $period (string) — The type of period to add (YEAR, MONTH, WEEK, DAY, ...)
  • It returns a Date value.

secondsToDays()

Returns the number of days represented by a number of seconds.

Signature

  • It accepts the following parameter(s):

    • $secs (int) —

  • It returns a float value.