PhoenixKit.Utils.Date (phoenix_kit v1.6.16)
View SourceDate and time formatting utilities for PhoenixKit.
This module provides robust date and time formatting functionality using Timex, supporting various format codes used throughout the PhoenixKit system.
Core Functions
Date Formatting
format_date/2- Format a date using PHP-style format codesformat_time/2- Format a time using PHP-style format codesget_date_examples/1- Generate example formatted datesget_time_examples/1- Generate example formatted times
Format Support
The module supports the following format codes:
Date Formats:
Y-m-d- 2025-09-02 (ISO format)m/d/Y- 09/02/2025 (US format)d/m/Y- 02/09/2025 (European format)d.m.Y- 02.09.2025 (German format)d-m-Y- 02-09-2025 (Alternative European)F j, Y- September 2, 2025 (Long format)
Time Formats:
H:i- 15:30 (24-hour format)h:i A- 3:30 PM (12-hour format with AM/PM)
Usage Examples
# Format a date
date = Date.utc_today()
PhoenixKit.Utils.Date.format_date(date, "F j, Y")
# => "September 2, 2025"
# Format a time
time = Time.utc_now()
PhoenixKit.Utils.Date.format_time(time, "h:i A")
# => "3:30 PM"
# Get examples for all date formats
PhoenixKit.Utils.Date.get_date_examples(Date.utc_today())
# => %{"Y-m-d" => "2025-09-02", "F j, Y" => "September 2, 2025", ...}Implementation
This module uses Elixir's built-in Calendar.strftime for robust date/time formatting with extensive format support.
Summary
Functions
Formats a date according to the specified format string.
Formats a date using pre-loaded date format settings (cache-optimized).
Formats a date using the user's date format preference from Settings.
Formats a date using the user's timezone and date format preferences.
Formats a date with timezone using pre-loaded settings (cache-optimized).
Formats a datetime (NaiveDateTime) according to the specified date format.
Formats a datetime (NaiveDateTime or DateTime) showing both date and time according to the specified date and time formats.
Formats a datetime showing both date and time using user preferences from Settings.
Formats a datetime using pre-loaded date format settings (cache-optimized).
Formats a datetime using the user's date format preference from Settings.
Formats a datetime using the user's timezone and date format preferences.
Formats a datetime with timezone using pre-loaded settings (cache-optimized).
Formats a time according to the specified format string.
Formats a time using pre-loaded time format settings (cache-optimized).
Formats a time using the user's time format preference from Settings. Automatically loads the time_format setting and applies it to the time.
Formats a time using the user's timezone and time format preferences.
Formats a time with timezone using pre-loaded settings (cache-optimized).
Generates example formatted dates for all supported formats.
Gets all supported date format options with dynamic examples.
Generates example formatted times for all supported formats.
Gets all supported time format options with dynamic examples.
Gets the effective timezone for a user.
Gets the effective timezone for a user using cached system timezone.
Functions
Formats a date according to the specified format string.
Uses Calendar.strftime for robust date formatting with extensive format support.
Examples
iex> PhoenixKit.Utils.Date.format_date(~D[2024-01-15], "Y-m-d")
"2024-01-15"
iex> PhoenixKit.Utils.Date.format_date(~D[2024-01-15], "m/d/Y")
"01/15/2024"
iex> PhoenixKit.Utils.Date.format_date(~D[2024-01-15], "F j, Y")
"January 15, 2024"Formats a date using pre-loaded date format settings (cache-optimized).
Examples
iex> settings = %{"date_format" => "F j, Y"}
iex> PhoenixKit.Utils.Date.format_date_with_cached_settings(~D[2024-01-15], settings)
"January 15, 2024"Formats a date using the user's date format preference from Settings.
Automatically loads the date_format setting and applies it to the date.
Examples
iex> PhoenixKit.Utils.Date.format_date_with_user_format(~D[2024-01-15])
"January 15, 2024" # If user has "F j, Y" format selectedFormats a date using the user's timezone and date format preferences.
Takes a user struct and uses their personal timezone preference if set, otherwise falls back to system timezone.
Examples
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.format_date_with_user_timezone(~D[2024-01-15], user)
"January 15, 2024" # If user has "F j, Y" format selectedFormats a date with timezone using pre-loaded settings (cache-optimized).
Examples
iex> settings = %{"date_format" => "F j, Y"}
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.format_date_with_user_timezone_cached(~D[2024-01-15], user, settings)
"January 15, 2024"Formats a datetime (NaiveDateTime) according to the specified date format.
Extracts the date part and formats it using format_date/2. Returns "Never" for nil values.
Examples
iex> PhoenixKit.Utils.Date.format_datetime(~N[2024-01-15 15:30:00], "F j, Y")
"January 15, 2024"
iex> PhoenixKit.Utils.Date.format_datetime(nil, "Y-m-d")
"Never"Formats a datetime (NaiveDateTime or DateTime) showing both date and time according to the specified date and time formats.
Returns "Never" for nil values.
Examples
iex> PhoenixKit.Utils.Date.format_datetime_full(~N[2024-01-15 15:30:00], "F j, Y", "h:i A")
"January 15, 2024 3:30 PM"
iex> PhoenixKit.Utils.Date.format_datetime_full(nil, "Y-m-d", "H:i")
"Never"Formats a datetime showing both date and time using user preferences from Settings.
Automatically loads date_format and time_format settings and applies them. Returns "Never" for nil values.
Examples
iex> PhoenixKit.Utils.Date.format_datetime_full_with_user_format(~N[2024-01-15 15:30:00])
"January 15, 2024 3:30 PM" # If user has "F j, Y" and "h:i A" formats selected
iex> PhoenixKit.Utils.Date.format_datetime_full_with_user_format(nil)
"Never"Formats a datetime using pre-loaded date format settings (cache-optimized).
This function accepts pre-loaded settings to avoid database queries, providing significant performance improvements when formatting many dates.
Examples
iex> settings = %{"date_format" => "F j, Y"}
iex> PhoenixKit.Utils.Date.format_datetime_with_cached_settings(~N[2024-01-15 15:30:00], settings)
"January 15, 2024"
iex> PhoenixKit.Utils.Date.format_datetime_with_cached_settings(nil, %{})
"Never"Formats a datetime using the user's date format preference from Settings.
Automatically loads the date_format setting and applies it to the datetime. Returns "Never" for nil values.
Examples
iex> PhoenixKit.Utils.Date.format_datetime_with_user_format(~N[2024-01-15 15:30:00])
"January 15, 2024" # If user has "F j, Y" format selected
iex> PhoenixKit.Utils.Date.format_datetime_with_user_format(nil)
"Never"Formats a datetime using the user's timezone and date format preferences.
Takes a user struct and uses their personal timezone preference if set, otherwise falls back to system timezone, and finally UTC as last resort.
Examples
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.format_datetime_with_user_timezone(~N[2024-01-15 15:30:00], user)
"January 15, 2024" # If user has "F j, Y" format selected
iex> user = %User{user_timezone: nil} # Falls back to system timezone
iex> PhoenixKit.Utils.Date.format_datetime_with_user_timezone(~N[2024-01-15 15:30:00], user)
"2024-01-15" # System default formatFormats a datetime with timezone using pre-loaded settings (cache-optimized).
This function combines timezone conversion with cached date/time formatting for optimal performance when processing multiple users' data.
Examples
iex> settings = %{"date_format" => "F j, Y"}
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.format_datetime_with_user_timezone_cached(~N[2024-01-15 15:30:00], user, settings)
"January 15, 2024"Formats a time according to the specified format string.
Uses Calendar.strftime for robust time formatting with extensive format support.
Examples
iex> PhoenixKit.Utils.Date.format_time(~T[15:30:00], "H:i")
"15:30"
iex> PhoenixKit.Utils.Date.format_time(~T[15:30:00], "h:i A")
"3:30 PM"Formats a time using pre-loaded time format settings (cache-optimized).
Examples
iex> settings = %{"time_format" => "h:i A"}
iex> PhoenixKit.Utils.Date.format_time_with_cached_settings(~T[15:30:00], settings)
"3:30 PM"Formats a time using the user's time format preference from Settings. Automatically loads the time_format setting and applies it to the time.
Examples
iex> PhoenixKit.Utils.Date.format_time_with_user_format(~T[15:30:00])
"3:30 PM" # If user has "h:i A" format selectedFormats a time using the user's timezone and time format preferences.
Takes a user struct and uses their personal timezone preference if set, otherwise falls back to system timezone.
Examples
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.format_time_with_user_timezone(~T[15:30:00], user)
"3:30 PM" # If user has "h:i A" format selectedFormats a time with timezone using pre-loaded settings (cache-optimized).
Examples
iex> settings = %{"time_format" => "h:i A"}
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.format_time_with_user_timezone_cached(~T[15:30:00], user, settings)
"8:30 PM"Generates example formatted dates for all supported formats.
Returns a map with format codes as keys and formatted examples as values. Useful for generating dropdown options and previews.
Examples
iex> PhoenixKit.Utils.Date.get_date_examples(~D[2024-01-15])
%{
"Y-m-d" => "2024-01-15",
"m/d/Y" => "01/15/2024",
"d/m/Y" => "15/01/2024",
"d.m.Y" => "15.01.2024",
"d-m-Y" => "15-01-2024",
"F j, Y" => "January 15, 2024"
}Gets all supported date format options with dynamic examples.
Returns a list of {label, format_code} tuples suitable for dropdown menus. Each label includes the format description and a current date example.
Examples
iex> PhoenixKit.Utils.Date.get_date_format_options()
[
{"YYYY-MM-DD (2025-09-02)", "Y-m-d"},
{"MM/DD/YYYY (09/02/2025)", "m/d/Y"},
# ... more formats
]Generates example formatted times for all supported formats.
Returns a map with format codes as keys and formatted examples as values. Useful for generating dropdown options and previews.
Examples
iex> PhoenixKit.Utils.Date.get_time_examples(~T[15:30:00])
%{
"H:i" => "15:30",
"h:i A" => "3:30 PM"
}Gets all supported time format options with dynamic examples.
Returns a list of {label, format_code} tuples suitable for dropdown menus. Each label includes the format description and a current time example.
Examples
iex> PhoenixKit.Utils.Date.get_time_format_options()
[
{"24 Hour (15:30)", "H:i"},
{"12 Hour (3:30 PM)", "h:i A"}
]Gets the effective timezone for a user.
Returns the user's personal timezone if set, otherwise falls back to system timezone, and finally UTC as last resort.
Examples
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.get_user_timezone(user)
"+5"
iex> user = %User{user_timezone: nil}
iex> PhoenixKit.Utils.Date.get_user_timezone(user)
"0" # System defaultGets the effective timezone for a user using cached system timezone.
Optimized version that accepts pre-loaded system timezone setting.
Examples
iex> settings = %{"time_zone" => "+1"}
iex> user = %User{user_timezone: nil}
iex> PhoenixKit.Utils.Date.get_user_timezone_cached(user, settings)
"+1"
iex> user = %User{user_timezone: "+5"}
iex> PhoenixKit.Utils.Date.get_user_timezone_cached(user, %{})
"+5"