Skip to content

Latest commit

 

History

History
636 lines (288 loc) · 10.6 KB

Timezones.md

File metadata and controls

636 lines (288 loc) · 10.6 KB
Raw

Timezones

Helpers for handling timezone based event datetimes.

In our timezone logic, the term "local" refers to the locality of an event rather than the local WordPress timezone.

  • Full name: \StellarWP\Dates\Timezones

Constants

Constant Visibility Type Value
SITE_TIMEZONE public 'site'

Properties

timezones

Container for reusable DateTimeZone objects.

protected static array $timezones
  • This property is static.

Methods

init

public static init(): mixed
  • This method is static.

abbr

Attempts to provide the correct timezone abbreviation for the provided timezone string on the date given (and so should account for daylight saving time, etc).

public static abbr(string|\DateTime|\DateTimeImmutable $date, string|\DateTimeZone $timezone_string): string
  • This method is static.

Parameters:

Parameter Type Description
$date string|\DateTime|\DateTimeImmutable The date string representation or object.
$timezone_string string|\DateTimeZone The timezone string or object.

apply_offset

Applies an time offset to the specified date time.

public static apply_offset(string $datetime, int|string $offset, bool $invert = false): string
  • This method is static.

Parameters:

Parameter Type Description
$datetime string The date and time string in a valid date format.
$offset int|string (string or numeric offset)
$invert bool = false Whether the offset should be added (true) or
subtracted (false); signum operations carry over so
-(-23) = +23.

build_timezone_object

Returns a valid timezone object built from the passed timezone or from the site one if a timezone in not passed.

public static build_timezone_object(string|null|\DateTimeZone $timezone = null): \DateTimeZone
  • This method is static.

Parameters:

Parameter Type Description
$timezone string|null|\DateTimeZone A DateTimeZone object, a timezone string
or null to build an object using the site one.

Return Value:

The built DateTimeZone object.

clear_site_timezone_abbr

Wipe the cached site timezone abbreviation, if set.

public static clear_site_timezone_abbr(mixed $option_val): mixed
  • This method is static.

Parameters:

Parameter Type Description
$option_val mixed (passed through without modification)

convert_date_from_timezone

Converts a date string or timestamp to a destination timezone.

public static convert_date_from_timezone(string|int $date, string $from_timezone, string $to_timezone, string $format): string
  • This method is static.

Parameters:

Parameter Type Description
$date string|int Either a string parseable by the strtotime function or a UNIX timestamp.
$from_timezone string The timezone of the source date.
$to_timezone string The timezone the destination date should use.
$format string The format that should be used for the destination date.

Return Value:

The formatted and converted date.

generate_timezone_string_from_utc_offset

Helper function to retrieve the timezone string for a given UTC offset

public static generate_timezone_string_from_utc_offset(string $offset): string

This is a close copy of WooCommerce's wc_timezone_string() method

  • This method is static.

Parameters:

Parameter Type Description
$offset string UTC offset

get_system_timezone

Gets the system timezone.

public static get_system_timezone(): \DateTimeZone
  • This method is static.

get_timezone

Returns a DateTimeZone object matching the representation in $tzstring where possible, or else representing UTC (or, in the worst case, false).

public static get_timezone(string $tzstring, bool $with_fallback = true): \DateTimeZone|false

If optional parameter $with_fallback is true, which is the default, then in the event it cannot find/create the desired timezone it will try to return the UTC DateTimeZone before bailing.

  • This method is static.

Parameters:

Parameter Type Description
$tzstring string
$with_fallback bool = true

get_valid_timezone

Parses the timezone string to validate or convert it into a valid one.

public static get_valid_timezone(string|\DateTimeZone $timezone_candidate): string
  • This method is static.

Parameters:

Parameter Type Description
$timezone_candidate string|\DateTimeZone The timezone string candidate.

Return Value:

The validated timezone string or a valid timezone string alternative.

invalidate_caches

Clear any cached timezone-related values when appropriate.

protected static invalidate_caches(): mixed

Currently we are concerned only with the site timezone abbreviation.

  • This method is static.

is_mode

Confirms if the current timezone mode matches the $possible_mode.

public static is_mode(string $possible_mode): bool
  • This method is static.

Parameters:

Parameter Type Description
$possible_mode string

is_utc_offset

Tests to see if the timezone string is a UTC offset, ie "UTC+2".

public static is_utc_offset(string $timezone): bool
  • This method is static.

Parameters:

Parameter Type Description
$timezone string

is_valid_timezone

Whether the candidate timezone is a valid PHP timezone or a supported UTC offset.

public static is_valid_timezone(string $candidate): bool
  • This method is static.

Parameters:

Parameter Type Description
$candidate string

localize_date

Localizes a date or timestamp using WordPress timezone and returns it in the specified format.

public static localize_date(string $format = null, string|int $date = null, string $timezone = null): string|bool
  • This method is static.

Parameters:

Parameter Type Description
$format string The format the date shouuld be formatted to.
$date string|int The date UNIX timestamp or strtotime parseable string.
$timezone string An optional timezone string identifying the timezone the date shoudl be localized
to; defaults to the WordPress installation timezone (if available) or to the system
timezone.

Return Value:

The parsed date in the specified format and localized to the system or specified timezone, or false if the specified date is not a valid date string or timestamp or the specified timezone is not a valid timezone string.

maybe_get_tz_name

Try to figure out the Timezone name base on offset

public static maybe_get_tz_name(string|int|float $timezone): string
  • This method is static.

Parameters:

Parameter Type Description
$timezone string|int|float The timezone

Return Value:

The Guessed Timezone String

mode

Returns a string representing the timezone/offset currently desired for the display of dates and times.

public static mode(): string
  • This method is static.

timezone_from_utc_offset

Given a string in the form "UTC+2.5" returns the corresponding DateTimeZone object.

public static timezone_from_utc_offset(string $utc_offset_string): \DateTimeZone

If this is not possible or if $utc_offset_string does not match the expected pattern, boolean false is returned.

  • This method is static.

Parameters:

Parameter Type Description
$utc_offset_string string

Return Value:

| bool

to_tz

Tries to convert the provided $datetime to the timezone represented by $tzstring.

public static to_tz(string $datetime, string $tzstring): string

This is the sister function of self::to_utc() - please review the docs for that method for more information.

  • This method is static.

Parameters:

Parameter Type Description
$datetime string
$tzstring string

to_utc

Tries to convert the provided $datetime to UTC from the timezone represented by $tzstring.

public static to_utc(string $datetime, string $tzstring, string $format = null): string

Though the usual range of formats are allowed, $datetime ordinarily ought to be something like the "Y-m-d H:i:s" format (ie, no timezone information). If it itself contains timezone data, the results may be unexpected.

In those cases where the conversion fails to take place, the $datetime string will be returned untouched.

  • This method is static.

Parameters:

Parameter Type Description
$datetime string
$tzstring string
$format string The optional format of the resulting date, defaults to
Dates::DBDATETIMEFORMAT.

wp_timezone_abbr

Returns the current site-wide timezone string abbreviation, if it can be determined or falls back on the full timezone string/offset text.

public static wp_timezone_abbr(string $date): string
  • This method is static.

Parameters:

Parameter Type Description
$date string

wp_timezone_string

Returns the current site-wide timezone string.

public static wp_timezone_string(): string

Based on the core WP code found in wp-admin/options-general.php.

  • This method is static.

Automatically generated from source code comments on 2023-08-19 using phpDocumentor and saggre/phpdocumentor-markdown