Class CakeTime

Time Helper class for easy use of time data.

Manipulation of time data.

Package: Cake\Utility
Link: http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/Utility/CakeTime.php

Properties summary

$_time protected static

integer

Temporary variable containing the timestamp value, used internally in convertSpecifiers()
$niceFormat public static

string

The format to use when formatting a time using CakeTime::nice()
$niceShortFormat public static

string

The format to use when formatting a time using CakeTime::niceShort() and the difference is between 3 and 7 days
$wordAccuracy public static

array

The format to use when formatting a time using CakeTime::timeAgoInWords() and the difference is less than CakeTime::$wordEnd
$wordEnd public static

string

The end of relative time telling
$wordFormat public static

string

The format to use when formatting a time using CakeTime::timeAgoInWords() and the difference is more than CakeTime::$wordEnd

Method Summary

__get() public

Magic set method for backwards compatibility. Used by TimeHelper to get static variables in CakeTime
__set() public

Magic set method for backwards compatibility. Used by TimeHelper to modify static variables in CakeTime
_strftime() protected static

Multibyte wrapper for strftime.
_translateSpecifier() protected static

Auxiliary function to translate a matched specifier element from a regular expression into a Windows safe and i18n aware specifier
convert() public static

Converts given time (in server's time zone) to user's local time, given his/her timezone.
convertSpecifiers() public static

Converts a string representing the format for the function strftime and returns a Windows safe and i18n aware format.
dayAsSql() public static

Returns a partial SQL string to search for all records between two times occurring on the same day.
daysAsSql() public static

Returns a partial SQL string to search for all records between two dates.
format() public static

Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string. This function also accepts a time string and a format string as first and second parameters. In that case this function behaves as a wrapper for TimeHelper::i18nFormat()
fromString() public static

Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.
gmt() public static

Returns gmt as a UNIX timestamp.
i18nFormat() public static

Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string. It takes into account the default date format for the current language if a LC_TIME file is used.
isFuture() public static

Returns true if given datetime string is in the future.
isPast() public static

Returns true if given datetime string is in the past.
isThisMonth() public static

Returns true if given datetime string is within this month
isThisWeek() public static

Returns true if given datetime string is within this week.
isThisYear() public static

Returns true if given datetime string is within current year.
isToday() public static

Returns true if given datetime string is today.
isTomorrow() public static

Returns true if given datetime string is tomorrow.
isWithinNext() public static

Returns true if specified datetime is within the interval specified, else false.
listTimezones() public static

Get list of timezone identifiers
nice() public static

Returns a nicely formatted date string for given Datetime string.
niceShort() public static

Returns a formatted descriptive date string for given datetime string.
serverOffset() public static

Returns server's offset from GMT in seconds.
timeAgoInWords() public static

Returns either a relative or a formatted absolute date depending on the difference between the current time and given datetime. $datetime should be in a strtotime - parsable format, like MySQL's datetime datatype.
timezone() public static

Returns a timezone object from a string or the user's timezone object
toAtom() public static

Returns a date formatted for Atom RSS feeds.
toQuarter() public static

Returns the quarter
toRSS() public static

Formats date for RSS feeds
toServer() public static

Returns a formatted date in server's timezone.
toUnix() public static

Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().
wasWithinLast() public static

Returns true if specified datetime was within the interval specified, else false.
wasYesterday() public static

Returns true if given datetime string was yesterday.

Method Detail

__get() public ¶

__get( string $name )

Magic set method for backwards compatibility. Used by TimeHelper to get static variables in CakeTime

Parameters

string $name: Variable name

Returns

mixed

__set() public ¶

__set( string $name , mixes $value )

Magic set method for backwards compatibility. Used by TimeHelper to modify static variables in CakeTime

Parameters

string $name: Variable name
mixes $value: Variable value

_strftime() protected static ¶

_strftime( string $format , integer $date )

Multibyte wrapper for strftime.

Handles utf8_encoding the result of strftime when necessary.

Parameters

string $format: Format string.
integer $date: Timestamp to format.

Returns

string
formatted string with correct encoding.

_translateSpecifier() protected static ¶

_translateSpecifier( array $specifier )

Auxiliary function to translate a matched specifier element from a regular expression into a Windows safe and i18n aware specifier

Parameters

array $specifier: match from regular expression

Returns

string
converted element

convert() public static ¶

convert( string $serverTime , string|DateTimeZone $timezone )

Converts given time (in server's time zone) to user's local time, given his/her timezone.

Parameters

string $serverTime: UNIX timestamp
string|DateTimeZone $timezone: User's timezone string or DateTimeZone object

Returns

integer
UNIX timestamp

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::convert

convertSpecifiers() public static ¶

convertSpecifiers( string $format , string $time = null )

Converts a string representing the format for the function strftime and returns a Windows safe and i18n aware format.

Parameters

string $format: Format with specifiers for strftime function. Accepts the special specifier %S which mimics the modifier S for date()
string $time optional null: UNIX timestamp

Returns

string
Windows safe and date() function compatible format for strftime

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::convertSpecifiers

dayAsSql() public static ¶

dayAsSql( integer|string|DateTime $dateString , string $fieldName , string|DateTimeZone $timezone = null )

Returns a partial SQL string to search for all records between two times occurring on the same day.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string $fieldName: Name of database field to compare with
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Partial SQL string.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::dayAsSql

daysAsSql() public static ¶

Returns a partial SQL string to search for all records between two dates.

Parameters

integer|string|DateTime $begin: UNIX timestamp, strtotime() valid string or DateTime object
integer|string|DateTime $end: UNIX timestamp, strtotime() valid string or DateTime object
string $fieldName: Name of database field to compare with
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Partial SQL string.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::daysAsSql

format() public static ¶

Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string. This function also accepts a time string and a format string as first and second parameters. In that case this function behaves as a wrapper for TimeHelper::i18nFormat()

Examples

Create localized & formatted time:

CakeTime::format('2012-02-15', '%m-%d-%Y'); // returns 02-15-2012
  CakeTime::format('2012-02-15 23:01:01', '%c'); // returns preferred date and time based on configured locale
  CakeTime::format('0000-00-00', '%d-%m-%Y', 'N/A'); // return N/A becuase an invalid date was passed
  CakeTime::format('2012-02-15 23:01:01', '%c', 'N/A', 'America/New_York'); // converts passed date to timezone

Parameters

integer|string|DateTime $date: UNIX timestamp, strtotime() valid string or DateTime object (or a date format string)
integer|string|DateTime $format optional null: date format string (or UNIX timestamp, strtotime() valid string or DateTime object)
boolean|string $default optional false: if an invalid date is passed it will output supplied default value. Pass false if you want raw conversion value
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Formatted date string

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::format

See

CakeTime::i18nFormat()

fromString() public static ¶

fromString( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Parsed timestamp

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::fromString

gmt() public static ¶

gmt( integer|string|DateTime $dateString = null )

Returns gmt as a UNIX timestamp.

Parameters

integer|string|DateTime $dateString optional null: UNIX timestamp, strtotime() valid string or DateTime object

Returns

integer
UNIX timestamp

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::gmt

i18nFormat() public static ¶

i18nFormat( integer|string|DateTime $date , string $format = null , boolean|string $default = false , string|DateTimeZone $timezone = null )

Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string. It takes into account the default date format for the current language if a LC_TIME file is used.

Parameters

integer|string|DateTime $date: UNIX timestamp, strtotime() valid string or DateTime object
string $format optional null: strftime format string.
boolean|string $default optional false: if an invalid date is passed it will output supplied default value. Pass false if you want raw conversion value
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Formatted and translated date string

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::i18nFormat

isFuture() public static ¶

isFuture( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string is in the future.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string is in the future

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::isFuture

isPast() public static ¶

isPast( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string is in the past.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string is in the past

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::isPast

isThisMonth() public static ¶

isThisMonth( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string is within this month

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string is within current month

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::isThisMonth

isThisWeek() public static ¶

isThisWeek( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string is within this week.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string is within current week

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::isThisWeek

isThisYear() public static ¶

isThisYear( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string is within current year.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string is within current year

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::isThisYear

isToday() public static ¶

isToday( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string is today.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string is today

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::isToday

isTomorrow() public static ¶

isTomorrow( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string is tomorrow.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string was yesterday

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::isTomorrow

isWithinNext() public static ¶

isWithinNext( string|integer $timeInterval , integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if specified datetime is within the interval specified, else false.

Parameters

string|integer $timeInterval: the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute.
integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean

listTimezones() public static ¶

listTimezones( integer|string $filter = null , string $country = null , boolean $group = true )

Get list of timezone identifiers

Parameters

integer|string $filter optional null: A regex to filter identifier Or one of DateTimeZone class constants (PHP 5.3 and above)
string $country optional null: A two-letter ISO 3166-1 compatible country code. This option is only used when $filter is set to DateTimeZone::PER_COUNTRY (available only in PHP 5.3 and above)
boolean $group optional true: If true (default value) groups the identifiers list by primary region

Returns

array
List of timezone identifiers

Since

2.2

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::listTimezones

nice() public static ¶

nice( integer|string|DateTime $dateString = null , string|DateTimeZone $timezone = null , string $format = null )

Returns a nicely formatted date string for given Datetime string.

See http://php.net/manual/en/function.strftime.php for information on formatting using locale strings.

Parameters

integer|string|DateTime $dateString optional null: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object
string $format optional null: The format to use. If null, CakeTime::$niceFormat is used

Returns

string
Formatted date string

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::nice

niceShort() public static ¶

niceShort( integer|string|DateTime $dateString = null , string|DateTimeZone $timezone = null )

Returns a formatted descriptive date string for given datetime string.

If the given date is today, the returned string could be "Today, 16:54". If the given date is tomorrow, the returned string could be "Tomorrow, 16:54". If the given date was yesterday, the returned string could be "Yesterday, 16:54". If the given date is within next or last week, the returned string could be "On Thursday, 16:54". If $dateString's year is the current year, the returned string does not include mention of the year.

Parameters

integer|string|DateTime $dateString optional null: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Described, relative date string

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::niceShort

serverOffset() public static ¶

serverOffset( )

Returns server's offset from GMT in seconds.

Returns

integer
Offset

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::serverOffset

timeAgoInWords() public static ¶

timeAgoInWords( integer|string|DateTime $dateTime , array $options = array() )

Returns either a relative or a formatted absolute date depending on the difference between the current time and given datetime. $datetime should be in a strtotime - parsable format, like MySQL's datetime datatype.

Options:

format => a fall back format if the relative time is longer than the duration specified by end
accuracy => Specifies how accurate the date should be described (array)
- year => The format if years > 0 (default "day")
- month => The format if months > 0 (default "day")
- week => The format if weeks > 0 (default "day")
- day => The format if weeks > 0 (default "hour")
- hour => The format if hours > 0 (default "minute")
- minute => The format if minutes > 0 (default "minute")
- second => The format if seconds > 0 (default "second")
end => The end of relative time telling
relativeString => The printf compatible string when outputting past relative time
relativeStringFuture => The printf compatible string when outputting future relative time
absoluteString => The printf compatible string when outputting absolute time
userOffset => Users offset from GMT (in hours) Deprecated use timezone instead.
timezone => The user timezone the timestamp should be formatted in.

Relative dates look something like this:

3 weeks, 4 days ago
15 seconds ago

Default date formatting is d/m/yy e.g: on 18/2/09

The returned string includes 'ago' or 'on' and assumes you'll properly add a word like 'Posted ' before the function output.

NOTE: If the difference is one week or more, the lowest level of accuracy is day

Parameters

integer|string|DateTime $dateTime: Datetime UNIX timestamp, strtotime() valid string or DateTime object
array $options optional array(): Default format if timestamp is used in $dateString

Returns

string
Relative time string.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::timeAgoInWords

timezone() public static ¶

timezone( string|DateTimeZone $timezone = null )

Returns a timezone object from a string or the user's timezone object

Parameters

string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object If null it tries to get timezone from 'Config.timezone' config var

Returns

DateTimeZone
Timezone object

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::timezone

toAtom() public static ¶

toAtom( string $dateString , string|DateTimeZone $timezone = null )

Returns a date formatted for Atom RSS feeds.

Parameters

string $dateString: Datetime string or Unix timestamp
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Formatted date string

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::toAtom

toQuarter() public static ¶

toQuarter( integer|string|DateTime $dateString , boolean $range = false )

Returns the quarter

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
boolean $range optional false: if true returns a range in Y-m-d format

Returns

integer|array
1, 2, 3, or 4 quarter of year or array if $range true

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::toQuarter

toRSS() public static ¶

toRSS( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Formats date for RSS feeds

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

string
Formatted date string

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::toRSS

toServer() public static ¶

toServer( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null , string $format = 'Y-m-d H:i:s' )

Returns a formatted date in server's timezone.

If a DateTime object is given or the dateString has a timezone segment, the timezone parameter will be ignored.

If no timezone parameter is given and no DateTime object, the passed $dateString will be considered to be in the UTC timezone.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object
string $format optional 'Y-m-d H:i:s': date format string

Returns

mixed
Formatted date

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::toServer

toUnix() public static ¶

toUnix( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

integer
Unix timestamp

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::toUnix

wasWithinLast() public static ¶

wasWithinLast( string|integer $timeInterval , integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if specified datetime was within the interval specified, else false.

Parameters

string|integer $timeInterval: the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute.
integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::wasWithinLast

wasYesterday() public static ¶

wasYesterday( integer|string|DateTime $dateString , string|DateTimeZone $timezone = null )

Returns true if given datetime string was yesterday.

Parameters

integer|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone $timezone optional null: Timezone string or DateTimeZone object

Returns

boolean
True if datetime string was yesterday

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#TimeHelper::wasYesterday

Properties detail

`$_time` ¶

protected static integer

Temporary variable containing the timestamp value, used internally in convertSpecifiers()

null

`$niceFormat` ¶

public static string

The format to use when formatting a time using CakeTime::nice()

The format should use the locale strings as defined in the PHP docs under strftime (http://php.net/manual/en/function.strftime.php)

See

CakeTime::format()

'%a, %b %eS %Y, %H:%M'

`$niceShortFormat` ¶

public static string

The format to use when formatting a time using CakeTime::niceShort() and the difference is between 3 and 7 days

See

CakeTime::niceShort()

'%B %d, %H:%M'

`$wordAccuracy` ¶

public static array

The format to use when formatting a time using CakeTime::timeAgoInWords() and the difference is less than CakeTime::$wordEnd

See

CakeTime::timeAgoInWords()

array(
    'year' => 'day',
    'month' => 'day',
    'week' => 'day',
    'day' => 'hour',
    'hour' => 'minute',
    'minute' => 'minute',
    'second' => 'second',
)

`$wordEnd` ¶

public static string

The end of relative time telling

See

CakeTime::timeAgoInWords()

'+1 month'

`$wordFormat` ¶

public static string

The format to use when formatting a time using CakeTime::timeAgoInWords() and the difference is more than CakeTime::$wordEnd

See

CakeTime::timeAgoInWords()

'j/n/y'

Packages

Classes

Class CakeTime

Properties summary

Method Summary

__get() public

__set() public

_strftime() protected static

_translateSpecifier() protected static

convert() public static

convertSpecifiers() public static

dayAsSql() public static

daysAsSql() public static

format() public static

fromString() public static

gmt() public static

i18nFormat() public static

isFuture() public static

isPast() public static

isThisMonth() public static

isThisWeek() public static

isThisYear() public static

isToday() public static

isTomorrow() public static

isWithinNext() public static

listTimezones() public static

nice() public static

niceShort() public static

serverOffset() public static

timeAgoInWords() public static

timezone() public static

toAtom() public static

toQuarter() public static

toRSS() public static

toServer() public static

toUnix() public static

wasWithinLast() public static

wasYesterday() public static

Method Detail

__get() public ¶

Parameters

Returns

__set() public ¶

Parameters

_strftime() protected static ¶

Parameters

Returns

_translateSpecifier() protected static ¶

Parameters

Returns

convert() public static ¶

Parameters

Returns

Link

convertSpecifiers() public static ¶

Parameters

Returns

Link

dayAsSql() public static ¶

Parameters

Returns

Link

daysAsSql() public static ¶

Parameters

Returns

Link

format() public static ¶

Examples

Parameters

Returns

Link

See

fromString() public static ¶

Parameters

Returns

Link

gmt() public static ¶

Parameters

Returns

Link