Documentation

Time extends DateTime
in package

SMF

implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Extends \DateTime with some extra features for SMF.

Interfaces

ArrayAccess

Constants

FORMAT_EQUIVALENTS = [ // Day 'a' => 'D', // Complex: prefer Lang::$txt strings if available. 'A' => 'l', // Complex: prefer Lang::$txt strings if available. 'e' => 'j', // Complex: sprintf to prepend whitespace. 'd' => 'd', 'j' => 'z', // Complex: must add one and then sprintf to prepend zeros. 'u' => 'N', 'w' => 'w', // Week 'U' => 'z_w_0', // Complex: calculated from these other values. 'V' => 'W', 'W' => 'z_w_1', // Complex: calculated from these other values. // Month 'b' => 'M', // Complex: prefer Lang::$txt strings if available. 'B' => 'F', // Complex: prefer Lang::$txt strings if available. 'm' => 'm', // Year 'C' => 'Y', // Complex: Get 'Y' then truncate to first two digits. 'g' => 'o', // Complex: Get 'o' then truncate to last two digits. 'G' => 'o', // Complex: Get 'o' then sprintf to ensure four digits. 'y' => 'y', 'Y' => 'Y', // Time 'H' => 'H', 'k' => 'G', 'I' => 'h', 'l' => 'g', // Complex: sprintf to prepend whitespace. 'M' => 'i', 'p' => 'A', // Complex: prefer Lang::$txt strings if available. 'P' => 'a', // Complex: prefer Lang::$txt strings if available. 'S' => 's', 'z' => 'O', 'Z' => 'T', // Time and Date Stamps 'c' => 'c', 's' => 'U', // Miscellaneous 'n' => "\n", 't' => "\t", '%' => '%', ]: Used for translating strftime format to DateTime format.
FORMAT_SHORT_FORMS = ['%h' => '%b', '%r' => '%I:%M:%S %p', '%R' => '%H:%M', '%T' => '%H:%M:%S', '%X' => '%H:%M:%S', '%D' => '%m/%d/%y', '%F' => '%Y-%m-%d', '%x' => '%Y-%m-%d']: Makes life easier when translating strftime format to DateTime format.
REGEX_STRFTIME = '%([ABCDFGHIMPRSTUVWXYZabcdeghjklmnprstuwxyz%])': A regular expression to match all known strftime format specifiers.

Properties

$date_format_no_year : string
$formats : array<string|int, mixed>
$short_date_format : string
$short_time_format : string
$today : array<string|int, mixed>
$user_tz : object
$backcompat : array<string|int, mixed>

Methods

__construct() : mixed: Constructor.
__get() : mixed: Gets custom property values.
__isset() : bool: Checks whether a custom property has been set.
__set() : void: Sets custom properties.
create() : object: Convenience wrapper for constuctor.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
format() : string: Like DateTime::format(), except that it can accept both DateTime format specifiers and strftime format specifiers (but not both at once).
forumTime() : int: Backward compatibility method.
getDateFormat() : string: Returns a strftime format or DateTime format for showing dates.
getDateOrTimeFormat() : string: Gets a version of a strftime format or DateTime format that only shows the date or time components.
getShortDateFormat() : string: Returns a compact strftime format or DateTime format for showing dates.
getShortTimeFormat() : string: Returns a compact strftime format or DateTime format for showing times.
getTimeFormat() : string: Returns a strftime format or DateTime format for showing times.
gmstrftime() : string: Replacement for gmstrftime() that is compatible with PHP 8.1+.
offsetExists() : bool: Checks whether a property has been set when object is accessed as an array.
offsetGet() : mixed: Gets properties when object is accessed as an array.
offsetSet() : void: Sets properties when object is accessed as an array.
offsetUnset() : void: Unsets properties when object is accessed as an array.
strftime() : string: Replacement for strftime() that is compatible with PHP 8.1+.
timeformat() : string: Backward compatibility wrapper for the format method.
datetimePartialFormat() : string: Gets a version of a DateTime format that only shows the date or time components.
isStrftimeFormat() : bool: Figures out whether the passed format is a strftime format.
strftimePartialFormat() : string: Gets a version of a strftime format that only shows the date or time components.

FORMAT_EQUIVALENTS

Used for translating strftime format to DateTime format.


    public
        mixed
    FORMAT_EQUIVALENTS
    = [
    // Day
    'a' => 'D',
    // Complex: prefer Lang::$txt strings if available.
    'A' => 'l',
    // Complex: prefer Lang::$txt strings if available.
    'e' => 'j',
    // Complex: sprintf to prepend whitespace.
    'd' => 'd',
    'j' => 'z',
    // Complex: must add one and then sprintf to prepend zeros.
    'u' => 'N',
    'w' => 'w',
    // Week
    'U' => 'z_w_0',
    // Complex: calculated from these other values.
    'V' => 'W',
    'W' => 'z_w_1',
    // Complex: calculated from these other values.
    // Month
    'b' => 'M',
    // Complex: prefer Lang::$txt strings if available.
    'B' => 'F',
    // Complex: prefer Lang::$txt strings if available.
    'm' => 'm',
    // Year
    'C' => 'Y',
    // Complex: Get 'Y' then truncate to first two digits.
    'g' => 'o',
    // Complex: Get 'o' then truncate to last two digits.
    'G' => 'o',
    // Complex: Get 'o' then sprintf to ensure four digits.
    'y' => 'y',
    'Y' => 'Y',
    // Time
    'H' => 'H',
    'k' => 'G',
    'I' => 'h',
    'l' => 'g',
    // Complex: sprintf to prepend whitespace.
    'M' => 'i',
    'p' => 'A',
    // Complex: prefer Lang::$txt strings if available.
    'P' => 'a',
    // Complex: prefer Lang::$txt strings if available.
    'S' => 's',
    'z' => 'O',
    'Z' => 'T',
    // Time and Date Stamps
    'c' => 'c',
    's' => 'U',
    // Miscellaneous
    'n' => "\n",
    't' => "\t",
    '%' => '%',
]

Keys are strftime format specifiers, without the leading '%'. Values are DateTime format specifiers, some of which will need further processing.

Note: %c produces locale-specific output in the original strftime library, but in this class its output will always use ISO 8601 format. This is due to the lack of locale support in the base DateTime class.

FORMAT_SHORT_FORMS

Makes life easier when translating strftime format to DateTime format.


    public
        mixed
    FORMAT_SHORT_FORMS
    = ['%h' => '%b', '%r' => '%I:%M:%S %p', '%R' => '%H:%M', '%T' => '%H:%M:%S', '%X' => '%H:%M:%S', '%D' => '%m/%d/%y', '%F' => '%Y-%m-%d', '%x' => '%Y-%m-%d']

Keys are short strftime formats. Values are expanded strftime formats.

Note: %x and %X produce locale-specific output in the original strftime library, but in this class their output will always use ISO 8601 format. This is due to the lack of locale support in the base DateTime class.

REGEX_STRFTIME

A regular expression to match all known strftime format specifiers.


    public
        mixed
    REGEX_STRFTIME
    = '%([ABCDFGHIMPRSTUVWXYZabcdeghjklmnprstuwxyz%])'

$date_format_no_year


    protected
    static    string
    $date_format_no_year

Short version of user's preferred date format, without the year.

$formats


    protected
    static    array<string|int, mixed>
    $formats
     = []

Processed date and time format strings.

$short_date_format


    protected
    static    string
    $short_date_format

Short version of user's preferred date format, with the year.

$short_time_format


    protected
    static    string
    $short_time_format

Short version of user's preferred time format.

$today


    protected
    static    array<string|int, mixed>
    $today

Timestamps for today at midnight according to different time zones.

$user_tz


    protected
    static    object
    $user_tz

\DateTimeZone instance for the user's time zone.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['create' => 'create', 'strftime' => 'smf_strftime', 'gmstrftime' => 'smf_gmstrftime', 'getDateOrTimeFormat' => 'get_date_or_time_format', 'timeformat' => 'timeformat', 'forumTime' => 'forum_time']]

BackwardCompatibility settings for this class.

__construct()

Constructor.


    public
                    __construct([string $datetime = 'now' ][, DateTimeZone|string $timezone = null ]) : mixed

This is similar to the \DateTime constructor, with the following changes:

The second parameter will not be ignored if the first parameter is a Unix timestamp.
The default time zone is the user's time zone, rather than the system's default time zone.
The second parameter can be a \DateTimeZone object or a valid time zone identifier string. If a string is passed and that string is not a valid time zone identifier, it will be silently discarded in favour of the current user's time zone.

Parameters

$datetime : string = 'now': A date/time string that PHP can understand, or a Unix timestamp.
$timezone : DateTimeZone|string = null: The time zone of $datetime, either as a \DateTimeZone object or as a time zone identifier string. Defaults to the current user's time zone.

__get()

Gets custom property values.


    public
                    __get(string $prop) : mixed

Parameters

$prop : string: The property name.

__isset()

Checks whether a custom property has been set.


    public
                    __isset(string $prop) : bool

Parameters

$prop : string: The property name.

Return values

bool

__set()

Sets custom properties.


    public
                    __set(string $prop, mixed $value) : void

Parameters

$prop : string: The property name.
$value : mixed: The value to set.

create()

Convenience wrapper for constuctor.


    public
            static        create([string $datetime = 'now' ][, DateTimeZone|string $timezone = null ]) : object

This is just syntactical sugar to ease method chaining.

Parameters

$datetime : string = 'now': A date/time string that PHP can understand, or a Unix timestamp.
$timezone : DateTimeZone|string = null: The time zone of $datetime, either as a \DateTimeZone object or as a time zone identifier string. Defaults to the current user's time zone.

Return values

object

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

format()

Like DateTime::format(), except that it can accept both DateTime format specifiers and strftime format specifiers (but not both at once).


    public
                    format([string $format = null ][, bool $relative = null ][, bool $strftime = null ]) : string

This does not use the system's strftime library or locale setting when formatting using strftime format specifiers, so results may vary in a few cases from the results of strftime():

%a, %A, %b, %B, %p, %P: Output will use SMF's language strings to localize these values. If SMF's language strings have not been loaded, PHP's default English strings will be used.
%c, %x, %X: Output will always use ISO 8601 format.

Parameters

$format : string = null: The format string to use. Defaults to the current user's preferred time format.
$relative : bool = null: Whether to show "yesterday" and "today" for recent dates. Defaults to true if $format is empty, or false otherwise.
$strftime : bool = null: True if $format uses strftime format specifiers, false if it uses DateTime format specifiers. If null, attempts to detect the format type automatically.

Return values

string —

The formatted date and time.

forumTime()

Backward compatibility method.


    public
            static        forumTime([bool $use_user_offset = true ][, int $timestamp = null ]) : int

Parameters

$use_user_offset : bool = true: This parameter is deprecated and ignored.
$timestamp : int = null: A timestamp (null to use current time).

Return values

int —

Seconds since the Unix epoch.

getDateFormat()

Returns a strftime format or DateTime format for showing dates.


    public
            static        getDateFormat([string $format = '' ][, bool $strftime = null ]) : string

Returned string will be based on the current user's preferred strftime format string, but without any time components.

Parameters

$format : string = '': A strftime format or DateTime format to process. Defaults to User::$me->time_format.
$strftime : bool = null: True if $format uses strftime format specifiers, false if it uses DateTime format specifiers. If null, attempts to detect the format type automatically.

Return values

string —

A strftime format or DateTime format string.

getDateOrTimeFormat()

Gets a version of a strftime format or DateTime format that only shows the date or time components.


    public
            static        getDateOrTimeFormat([string $type = '' ][, string $format = '' ][, bool $strftime = null ]) : string

Parameters

$type : string = '': Either 'date' or 'time'.
$format : string = '': A strftime format or DateTime format to process. Defaults to User::$me->time_format.
$strftime : bool = null: True if $format uses strftime format specifiers, false if it uses DateTime format specifiers. If null, attempts to detect the format type automatically. Ignored if $format is empty.

Return values

string —

A strftime format or DateTime format string.

getShortDateFormat()

Returns a compact strftime format or DateTime format for showing dates.


    public
            static        getShortDateFormat([string $format = '' ][, bool $strftime = null ]) : string

Returned string will be based on the current user's preferred strftime format string, but without the year, time components, or extra fluff.

Parameters

$format : string = '': A strftime format or DateTime format to process. Defaults to User::$me->time_format.
$strftime : bool = null: True if $format uses strftime format specifiers, false if it uses DateTime format specifiers. If null, attempts to detect the format type automatically.

Return values

string —

A strftime format or DateTime format string.

getShortTimeFormat()

Returns a compact strftime format or DateTime format for showing times.


    public
            static        getShortTimeFormat([string $format = '' ][, bool $strftime = null ]) : string

Returned string will be based on the current user's preferred strftime format string, but without any date components or extra fluff.

Parameters

$format : string = '': A strftime format or DateTime format to process. Defaults to User::$me->time_format.
$strftime : bool = null: True if $format uses strftime format specifiers, false if it uses DateTime format specifiers. If null, attempts to detect the format type automatically.

Return values

string —

A strftime format or DateTime format string.

getTimeFormat()

Returns a strftime format or DateTime format for showing times.


    public
            static        getTimeFormat([string $format = '' ][, bool $strftime = null ]) : string

Returned string will be based on the current user's preferred strftime format string, but without any date components.

Parameters

$format : string = '': A strftime format or DateTime format to process. Defaults to User::$me->time_format.
$strftime : bool = null: True if $format uses strftime format specifiers, false if it uses DateTime format specifiers. If null, attempts to detect the format type automatically.

Return values

string —

A strftime format or DateTime format string.

gmstrftime()

Replacement for gmstrftime() that is compatible with PHP 8.1+.


    public
            static        gmstrftime(string $format[, int|null $timestamp = null ]) : string

Calls self::strftime() with the $tzid parameter set to 'UTC'.

Parameters

$format : string: A strftime() format string.
$timestamp : int|null = null: A Unix timestamp. If null, defaults to the current time.

Return values

string —

The formatted date and time.

offsetExists()

Checks whether a property has been set when object is accessed as an array.


    public
                    offsetExists(mixed $prop) : bool

Parameters

$prop : mixed: The property name.

Return values

bool

offsetGet()

Gets properties when object is accessed as an array.


    public
                    offsetGet(mixed $prop) : mixed

Parameters

$prop : mixed: The property name.

offsetSet()

Sets properties when object is accessed as an array.


    public
                    offsetSet(mixed $prop, mixed $value) : void

Parameters

$prop : mixed: The property name.
$value : mixed: The value to set.

offsetUnset()

Unsets properties when object is accessed as an array.


    public
                    offsetUnset(mixed $prop) : void

Parameters

$prop : mixed: The property name.

strftime()

Replacement for strftime() that is compatible with PHP 8.1+.


    public
            static        strftime(string $format[, int|null $timestamp = null ][, string|null $tzid = null ]) : string

Parameters

$format : string: A strftime() format string.
$timestamp : int|null = null: A Unix timestamp. If null, defaults to the current time.
$tzid : string|null = null: Time zone identifier. If null, uses default time zone.

Return values

string —

The formatted date and time.

timeformat()

Backward compatibility wrapper for the format method.


    public
            static        timeformat(int $log_time[, bool|string $show_today = true ][, string $tzid = null ]) : string

Parameters

$log_time : int: A timestamp.
$show_today : bool|string = true: Whether to show "Today"/"Yesterday" or just a date. If a string is specified, that is used to temporarily override the date format.
$tzid : string = null: Time zone identifier string of the time zone to use. If empty, the user's time zone will be used. If set to a valid time zone identifier, that will be used. Otherwise, the value of Config::$modSettings['default_timezone'] will be used.

Return values

string —

A formatted time string

datetimePartialFormat()

Gets a version of a DateTime format that only shows the date or time components.


    protected
            static        datetimePartialFormat(string $type, string $format) : string

Parameters

$type : string: Either 'date' or 'time'.
$format : string: A DateTime format to process.

Return values

string —

A DateTime format string.

isStrftimeFormat()

Figures out whether the passed format is a strftime format.


    protected
            static        isStrftimeFormat(string $format) : bool

Parameters

$format : string: The format string.

Return values

bool —

Whether is is a strftime format.

strftimePartialFormat()

Gets a version of a strftime format that only shows the date or time components.


    protected
            static        strftimePartialFormat(string $type, string $format) : string

Parameters

$type : string: Either 'date' or 'time'.
$format : string: A strftime format to process.

Return values

string —

A strftime format string.

Time extends DateTime in package SMF implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

FORMAT_EQUIVALENTS

FORMAT_SHORT_FORMS

REGEX_STRFTIME

Properties

$date_format_no_year

$formats

$short_date_format

$short_time_format

$today

$user_tz

$backcompat

Methods

__construct()

Parameters

__get()

Parameters

__isset()

Parameters

Return values

__set()

Parameters

create()

Parameters

Return values

exportStatic()

format()

Parameters

Return values

forumTime()

Parameters

Tags

Return values

getDateFormat()

Parameters

Return values

getDateOrTimeFormat()

Parameters

Return values

getShortDateFormat()

Parameters

Return values

getShortTimeFormat()

Parameters

Return values

getTimeFormat()

Parameters

Return values

gmstrftime()

Parameters

Return values

offsetExists()

Parameters

Return values

offsetGet()

Parameters

offsetSet()

Parameters

offsetUnset()

Parameters

strftime()

Parameters

Return values

timeformat()

Parameters

Return values

datetimePartialFormat()

Parameters

Return values

isStrftimeFormat()

Parameters

Return values

strftimePartialFormat()

Parameters

Time extends DateTime
in package

SMF

implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper