Date Class

The Date class is a set of helper functions for working with dates, contrary to PHP's DateTime class the Fuel Date class has full support for i18n. You can also use the Date class for timezone conversions.

forge($timestamp = null, $timezone = null)

The forge method returns a new date object.

Static Yes
Parameters
Param Default Description
$timestamp 
null
 The timestamp to set the date object to
$timezone 
null
 The timezone in which the time is set
Returns Fuel\Core\Date Object
Example 
print_r(Date::forge(1294176140));

// Returns
Fuel\Core\Date Object
(
    [timestamp:protected] => 1294176140
    [timezone:protected] => UTC
)

time($timezone = null)

The time method returns the current time in the given timezone as a Date object.

Static Yes
Parameters
Param Default Description
$timezone 
null
 The timezone in which the time is set
Returns Fuel\Core\Date Object
Example 
print_r(Date::time());

display_timezone($timezone = null)

The display_timezone method allows you to globally set a timezone which can be used by the format() method to generate output in another timezone then the system timezone. If you don't pass a parameter, the current display_timezone is returned.

Static Yes
Parameters
Param Default Description
$timezone 
null
 The display timezone to be used to format timestamps in a non-system timezone.
Returns mixed, null, or the current display timezone if no parameter is passed.
Example 
// set the display timezone to 'America/Lima'
Date::display_timezone('America/Lima');

create_from_string($input, $pattern_key = 'local')

The create_from_string creates a Date object from a named date string format or a pattern.

This function uses strptime(). This method isn't available on Windows hosts, and deprecated in PHP 8.1. In those cases, we emulate it using Date::strptime(). Note that this doesn't have locale support (i.e. pattern values representing locale values, like %c).

Static Yes
Parameters
Param Default Description
$input Required The date string to use
$pattern_key "local" The pattern key to use (see config/date.php) or directly a strptime() pattern
Returns Fuel\Core\Date Object
Example 
print_r(Date::create_from_string("01/04/2011" , "us"));

// Returns
Fuel\Core\Date Object
(
    [timestamp:protected] => 1322956800
    [timezone:protected] => UTC
)

date_default_timezone_set('Europe/London');
print_r(Date::create_from_string("01/04/2011 -0900" , "%m/%d/%Y %z"))

// Returns
Fuel\Core\Date Object
(
    [timestamp:protected] => 1294135200
    [timezone:protected] => Europe/London
)

The Date object created is always in the currently active timezone. If a timezone is detected in the format, its offset will be taken into account when creating the object.

range_to_array($start, $end, $interval = '+1 Day')

The range_to_array converts a range of dates into an array of date objects

Static Yes
Parameters
Param Default Description
$start Required The start date either as a Date object or a timestamp
$end Required The end date either as a Date object or a timestamp
$interval "+1 Day" The interval at which to create a Date object
Returns array
Example 
$start = time();
$end = $start + 604800; // Plus 1 week
print_r(Date::range_to_array($start, $end, "+2 days"));

// Returns
Array
(
    [0] => Fuel\Core\Date Object
        (
            [timestamp:protected] => 1294181818
            [timezone:protected] => UTC
        )

    [1] => Fuel\Core\Date Object
        (
            [timestamp:protected] => 1294354618
            [timezone:protected] => UTC
        )

    [2] => Fuel\Core\Date Object
        (
            [timestamp:protected] => 1294527418
            [timezone:protected] => UTC
        )

    [3] => Fuel\Core\Date Object
        (
            [timestamp:protected] => 1294700218
            [timezone:protected] => UTC
        )
)

days_in_month($month, $year = null)

The days_in_month returns the number of days in any given month, in the year specified

Static Yes
Parameters
Param Default Description
$month Required The month to use
$year 
null
 The year to use (defaults to current year)
Returns int
Example 
echo Date::days_in_month(2);       // 28
echo Date::days_in_month(2, 2000); // 29

time_ago($timestamp, $now, $period)

The time_ago method returns a formatted time difference.

Static Yes
Parameters
Param Default Description
$timestamp Required The UNIX timestamp
$now Optional The UNIX timestamp to compare against. If not given or null, use the current time
$period Optional The timespan the answer is returned in. Possible values are 'second', 'minute', 'hour', 'day', 'week', 'month', 'year' and 'decade'. if none is specified, the largest possible is returned
Returns string
Example 
echo Date::time_ago(strtotime("01 January 2012")); // 1 months ago (when in February 2012)
echo Date::time_ago(strtotime("12 April 1964"), strtotime("01 March 2012")); // 5 decades ago
echo Date::time_ago(strtotime("12 April 1964"), strtotime("01 March 2012"), 'year'); // 48 years ago

is_valid($date, 'Y-m-d')

The is_valid returns whether the date value passed matches the given format, and if it is a valid date.

Static Yes
Parameters
Param Default Description
$date Required String, a date and/or time combination that can be expressed in a string.
$format 
'Y-m-d h:i:s'
 The format to match against (see the PHP docs)
Returns bool
Example 
echo \Date::is_valid('2019-01-01', 'Y-m-d') ? "true" : "false"; // true
echo \Date::is_valid('2019-01-32', 'Y-m-d') ? "true" : "false"; // false
echo \Date::is_valid('2019-02-28', 'Y-m-d') ? "true" : "false"; // true
echo \Date::is_valid('2019-02-29', 'Y-m-d') ? "true" : "false"; // false

strftime($format, $timestamp)

The strftime method is a drop-in replacedment for the PHP strftime() function, for use on Windows or PHP 8.1+.

Static Yes
Parameters
Param Default Description
$format 
'%Y-%m-%d %H:%M:%S'
 The format to render with (see the PHP docs)
$timestamp null Int, a valid unix timestamp. If not given, time() is used instead.
Returns bool
Example 
echo \Date::strftime("%d, %B, %Y", strtotime("01/03/2004")); // 03, januari, 2004
echo \Date::strftime("%I:%M  %p", strtotime("21:34")); // 09:34  PM

strptime($timestamp, $format)

The strptime method is a drop-in replacedment for the PHP strftime() function, for use on Windows or PHP 8.1+.

Static Yes
Parameters
Param Default Description
$timestamp required Int, a valid unix timestamp.
$format 
'%Y-%m-%d %H:%M:%S'
 The format to parse with (see the PHP docs)
Returns bool
Example 
$format = '%d/%m/%Y %H:%M:%S %z';
$strf = strftime($format);
echo "$strf\n";
print_r(strptime($strf, $format));

// will output something like

03/10/2004 15:54:19 +0200

Array
(
    [tm_sec] => 19
    [tm_min] => 54
    [tm_hour] => 15
    [tm_mday] => 3
    [tm_mon] => 9
    [tm_year] => 104
    [tm_wday] => 0
    [tm_yday] => 276
    [unparsed] =>
    [tm_zone] => 7200
)

Unlike the PHP built-in function, this version has support for timezones. If a timezone is detected in the format, like "%z" in the above example, an additional "tm_zone" value is returned in the array, indicating the offset to UTC, in seconds.

format($pattern_key = 'local', $timezone = null)

The format method returns a formatted date as specified by the pattern key. The patterns are defined in the fuel/core/config/date.php config file - you can add your own by creating a similar file in app/config.

This method uses patterns for the strftime() function instead of date() to allow for i18n. On PHP 8.1 or higher, or on platforms not supporting this function, it is emulated by Date::strftime().

If you don't pass a timezone, the timezone set on the current Date object will be used when formatting the result. By default, this is the system timezone, unless you have altered it by calling the set_timezone() method. You can also pass true which will cause the global display_timezone to be used.

You can use the display_timezone to globally set a timezone to convert to, for example from a user profile setting when a user is logged in. This will allow all dates to be displayed in the users local timezone.

Static No
Parameters
Param Default Description
$pattern_key "local" The pattern key to use (see config/date.php)
$timezone null The timezone to use when generating the formatted output
Returns string
Example 
// if the system time is UTC, this will return "01/04/2011 21:22"
echo Date::forge(1294176140)->format("%m/%d/%Y %H:%M");

// set the timezone to "Europe/Amsterdam" (which is GMT+1 in January), this will return "01/04/2011 22:22"
echo Date::forge(1294176140)->set_timezone('Europe/Amsterdam')->format("%m/%d/%Y %H:%M");

// set the display timezone globally to "Europe/Amsterdam"
Date::display_timezone('Europe/Amsterdam');

// this will return "01/04/2011 22:22" too
echo Date::forge(1294176140)->format("%m/%d/%Y %H:%M", true);

get_timestamp()

The get_timestamp method returns the Date object's timestamp

Static No
Returns int
Example 
echo Date::forge(1294176140)->get_timestamp(); // 1294176140

get_timezone()

The get_timezone method returns the Date object's timezone

Static No
Returns string
Example 
echo Date::forge(1294176140, "Europe/London")->get_timezone(); // Europe/London

get_timezone_abbr($display_timezone = false)

The get_timezone_abbr method returns the abbreviated timezone for either the timezone set in the Date object, or for the display timezone.

Static No
Parameters
Param Default Description
$display_timezone boolean if true, the global display_timezone is used instead of the timezone set on the Date object
Returns string
Example 
echo Date::forge(1294176140, "Europe/London")->get_timezone_abbr(); // returns "GMT"
echo Date::forge(1294176140, "Europe/Amsterdam")->get_timezone_abbr(); // returns "CET"

// set the display timezone globally to "Europe/Amsterdam"
Date::display_timezone('Europe/Amsterdam');
echo Date::forge(1294176140)->get_timezone_abbr(true); // returns "CET" too

set_timezone($timezone)

The set_timezone method sets the Date object's timezone

Static No
Parameters
Param Default Description
$timezone required The timezone to set the Date object to
Returns string
Example 
echo Date::forge(1294176140)->set_timezone("America/Chicago")->get_timezone(); // America/Chicago