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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source public static

daysAsSql( integer|string|DateTime $begin , integer|string|DateTime $end , string $fieldName , string|DateTimeZone $timezone null )

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()source public static

format( integer|string|DateTime $date , integer|string|DateTime $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. 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source public static

listTimezones( integer|string $filter null , string $country null , boolean|array $options array() )

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|array $options optional array(): If true (default value) groups the identifiers list by primary region. Otherwise, an array containing group, abbr, before, and after keys. Setting group and abbr to true will group results and append timezone abbreviation in the display value. Set before and after to customize the abbreviation wrapper.

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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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()source 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

$_timesource

protected static integer

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

null

$niceFormatsource

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'

$niceShortFormatsource

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'

$wordAccuracysource

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',
)

$wordEndsource

public static string

The end of relative time telling

See

CakeTime::timeAgoInWords()

'+1 month'

$wordFormatsource

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'

© 2005–2016 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
http://api.cakephp.org/2.8/class-CakeTime.html