Documentation

Time extends DateTime
in package

SMF

implements ArrayAccess uses 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>
$parsable_words_regex : string
$short_date_format : string
$short_time_format : string
$today : array<string|int, mixed>
$user_tz : object

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.
convertToEnglish() : string: Helper function to convert a date string to English so that date_parse() can parse it correctly.
create() : self: Convenience wrapper for constructor.
createFromImmutable() : static: Convert a \DateTimeImmutable object to a Time object.
createFromInterface() : static: Convert a \DateTimeInterface object to a Time object.
createFromMutable() : static: Convert a \DateTime object to a Time object.
format() : string: Like DateTime::format(), except that it can accept either DateTime format specifiers or strftime format specifiers (but not both at once).
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+.
isStrftimeFormat() : bool: Figures out whether the passed format is a strftime format.
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.
sanitize() : string: Removes text that the date parser wouldn't recognize.
setTimezone() : staitc: Sets the time zone for the SMF\Time object.
strftime() : string: Replacement for strftime() that is compatible with PHP 8.1+.
stringFromUnix() : string: Like self::strftime(), but always uses the current user's time zone and preferred time format.
datetimePartialFormat() : string: Gets a version of a DateTime format that only shows the date or time components.
setParsableWordsRegex() : void: Builds a regex to match words that the date parser recognizes and saves it in self::$parsable_words_regex.
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.

$parsable_words_regex


    protected
    static    string
    $parsable_words_regex

Regular expression to match all keywords recognized by PHP's date parser.

$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.

__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.

convertToEnglish()

Helper function to convert a date string to English so that date_parse() can parse it correctly.


    public
            static        convertToEnglish(string $date) : string

Parameters

$date : string: A localized date string.

Return values

string —

English date string.

create()

Convenience wrapper for constructor.


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

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

self —

An instance of this class.

createFromImmutable()

Convert a \DateTimeImmutable object to a Time object.


    public
            static        createFromImmutable(string $object) : static

Parameters

$object : string: A \DateTimeImmutable object.

Return values

static

createFromInterface()

Convert a \DateTimeInterface object to a Time object.


    public
            static        createFromInterface(string $object) : static

Parameters

$object : string: A \DateTimeInterface object.

Return values

static

createFromMutable()

Convert a \DateTime object to a Time object.


    public
            static        createFromMutable(string $object) : static

Parameters

$object : string: A \DateTime object.

Return values

static

format()

Like DateTime::format(), except that it can accept either DateTime format specifiers or 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.

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.

isStrftimeFormat()

Figures out whether the passed format is a strftime format.


    public
            static        isStrftimeFormat(string $format) : bool

Parameters

$format : string: The format string.

Return values

bool —

Whether it is a strftime format.

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.

Return values

mixed —

A reference to the property.

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.

sanitize()

Removes text that the date parser wouldn't recognize.


    public
            static        sanitize(string $datetime) : string

Parameters

$datetime : string: A date/time string that needs to be parsed.

Return values

string —

Sanitized version of $datetime.

setTimezone()

Sets the time zone for the SMF\Time object.


    public
                    setTimezone(DateTimeZone|string $timezone) : staitc

Parameters

$timezone : DateTimeZone|string: The desired time zone. Can be a \DateTimeZone object or a valid time zone identifier string.

Return values

staitc —

An reference to this object.

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.

stringFromUnix()

Like self::strftime(), but always uses the current user's time zone and preferred time format.


    public
            static        stringFromUnix([int|string|null $timestamp = null ]) : string

Parameters

$timestamp : int|string|null = null: A Unix timestamp. If null or invalid, defaults to the current time.

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.

setParsableWordsRegex()

Builds a regex to match words that the date parser recognizes and saves it in self::$parsable_words_regex.


    protected
            static        setParsableWordsRegex() : void

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 ArrayAccessHelper

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

FORMAT_EQUIVALENTS

FORMAT_SHORT_FORMS

REGEX_STRFTIME

Properties

$date_format_no_year

$formats

$parsable_words_regex

$short_date_format

$short_time_format

$today

$user_tz

Methods

__construct()

Parameters

__get()

Parameters

__isset()

Parameters

Return values

__set()

Parameters

convertToEnglish()

Parameters

Return values

create()

Parameters

Return values

createFromImmutable()

Parameters

Return values

createFromInterface()

Parameters

Return values

createFromMutable()

Parameters

Return values

format()

Parameters

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

isStrftimeFormat()

Parameters

Return values

offsetExists()

Parameters

Return values

offsetGet()

Parameters

Return values

offsetSet()

Parameters

offsetUnset()

Parameters

sanitize()

Parameters

Return values

Time extends DateTime
in package

SMF

implements ArrayAccess uses ArrayAccessHelper