README.md

StellarWP Dates

A collection of date utilities authored by the development team at StellarWP and provided free for the WordPress community.

This work is forked from the battle-tested date handling done at The Events Calendar!

Installation

It's recommended that you install Dates as a project dependency via Composer:

composer require stellarwp/dates

We actually recommend that this library gets included in your project using Strauss.

Luckily, adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.

Documentation

• How dates are built
• Constants
• Dates
  • build_date_object - alias for mutable()
  • build_localized_months
  • build_localized_weekdays
  • catch_and_throw
  • clear_cache
  • date - alias for date_only()
  • date_diff - alias for diff()
  • date_only
  • datetime_from_format
  • diff
  • first_day_in_month
  • get - calls immutable() (default) or mutable()
  • get_cache
  • get_first_day_of_week_in_month
  • get_last_day_of_month
  • get_last_day_of_week_in_month
  • get_localized_months_full
  • get_localized_months_short
  • get_localized_weekdays_full
  • get_localized_weekdays_initial
  • get_localized_weekdays_short
  • get_modifier_from_offset
  • get_week_start_end
  • get_weekday_timestamp
  • has_cache
  • hour - alias for hour_only()
  • hour_only
  • immutable
  • interval
  • is_after
  • is_before
  • is_between
  • is_now - calls is_between() with a different parameter order, where the date to look for is last and optional.
  • is_timestamp
  • is_valid
  • is_valid_date - alias for is_valid()
  • is_weekday
  • is_weekend
  • last_day_in_month
  • meridian - alias for meridian_only()
  • meridian_only
  • minutes
  • minutes_only
  • mutable
  • number_to_ordinal
  • range_coincides - alias for range_overlaps()
  • range_overlaps
  • reformat
  • round_nearest_half_hour
  • seconds - alias for seconds_only()
  • seconds_only
  • set_cache
  • sort
  • time_between
  • time - alias for time_only()
  • time_only
  • unescape_date_format
  • week_ends_on
  • wp_strtotime
  • wp_locale_month
  • wp_locale_weekday
• Date_I18n
  • createFromImmutable
  • format_i18n
• Date_I18n_Immutable
  • createFromMutable
  • format_i18n
• Timezones
  • abbr
  • apply_offset
  • build_timezone_object
  • clear_site_timezone_abbr
  • convert_date_from_timezone_to_timezone
  • generate_timezone_string_from_utc_offset
  • get_system_timezone
  • get_timezone
  • get_valid_timezone
  • invalided_caches
  • is_mode
  • is_utc_offest
  • is_valid_timezone
  • localize_date
  • maybe_get_tz_name
  • timezone_from_utc_offset
  • to_tz
  • to_utc
  • wp_timezone_abbr
  • wp_timezone_string

How dates are built

The Dates::get() method accepts a number of parameters (a date, a timezone, a fallback date, and an immutable flag). However, you can get the current datetime with a simple call to Dates::get() like so:

use StellarWP\Dates\Dates;

$date = Dates::get();

Whether you are using that simple approach or something more complex, here's what is happening under the hood:

flowchart TD
  is_immutable{"Immutable?"} -- yes --> yes_immutable["All dates returned will be Date_I18n_Immutable"]
  is_immutable -- no --> no_immutable["All dates returned will be Date_I18n"]
  yes_immutable --> is_timezone_set{"Is the timezone set?"}
  no_immutable --> is_timezone_set
  is_timezone_set -- yes --> create_timezone["Create a DateTimeZone object from $timezone"]
  is_timezone_set -- no --> is_wp_timezone_set{"Is there a WP timezone string?"}
  is_wp_timezone_set -- yes --> use_wp_timezone["$timezone = WP timezone string"]
  is_wp_timezone_set -- no --> is_timezone_valid{"Is $timezone valid?"}
  is_timezone_valid -- yes --> create_timezone
  is_timezone_valid -- no --> use_utc["$timezone = UTC"]
  use_wp_timezone --> create_timezone
  use_utc --> create_timezone
  create_timezone --> create_date["$date = date object using $datetime with $timezone"]
  create_date --> is_error{Error when creating date object?}
  is_error -- yes --> should_fallback{"Is a fallback date desired?"}
  should_fallback -- no --> no_fallback((Return false))
  should_fallback -- yes --> yes_fallaback["$date = 'now' date object with $timezone"]
  is_error -- no --> final
  yes_fallaback --> final((Return $date))

Loading

Constants

Constant	Format	Description
DATEONLYFORMAT	F j, Y	The date format used for date-only strings.
TIMEFORMAT	g:i A	The time format used for time-only strings.
HOURFORMAT	g	The hour format used for hour-only strings.
MINUTEFORMAT	i	The minute format used for minute-only strings.
MERIDIANFORMAT	A	The meridian format used for meridian-only strings.
DBDATEFORMAT	Y-m-d	The date format used for date-only strings in the database.
DBDATETIMEFORMAT	Y-m-d H:i:s	The date format used for date-time strings in the database.
DBTZDATETIMEFORMAT	Y-m-d H:i:s O	The date format used for date-time strings in the database with timezone.
DBTIMEFORMAT	H:i:s	The date format used for time-only strings in the database.
DBYEARMONTHTIMEFORMAT	Y-m	The date format used for year-month strings in the database.