Search documentation of phoenix_kit

# PhoenixKit.Utils.Date (phoenix_kit v1.6.19)

View Source

Date 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 codes
- `format_time/2` - Format a time using PHP-style format codes
- `get_date_examples/1` - Generate example formatted dates
- `get_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

format_date(date, format)

Formats a date according to the specified format string.

format_date_with_cached_settings(date, settings)

Formats a date using pre-loaded date format settings (cache-optimized).

format_date_with_user_format(date)

Formats a date using the user's date format preference from Settings.

format_date_with_user_timezone(date, user)

Formats a date using the user's timezone and date format preferences.

format_date_with_user_timezone_cached(date, user, settings)

Formats a date with timezone using pre-loaded settings (cache-optimized).

format_datetime(datetime, format)

Formats a datetime (NaiveDateTime) according to the specified date format.

format_datetime_full(datetime, date_format, time_format)

Formats a datetime (NaiveDateTime or DateTime) showing both date and time according to the specified date and time formats.

format_datetime_full_with_user_format(datetime)

Formats a datetime showing both date and time using user preferences from Settings.

format_datetime_with_cached_settings(datetime, settings)

Formats a datetime using pre-loaded date format settings (cache-optimized).

format_datetime_with_user_format(datetime)

Formats a datetime using the user's date format preference from Settings.

format_datetime_with_user_timezone(datetime, user)

Formats a datetime using the user's timezone and date format preferences.

format_datetime_with_user_timezone_cached(datetime, user, settings)

Formats a datetime with timezone using pre-loaded settings (cache-optimized).

format_time(time, format)

Formats a time according to the specified format string.

format_time_with_cached_settings(time, settings)

Formats a time using pre-loaded time format settings (cache-optimized).

format_time_with_user_format(time)

Formats a time using the user's time format preference from Settings. Automatically loads the time_format setting and applies it to the time.

format_time_with_user_timezone(time, user)

Formats a time using the user's timezone and time format preferences.

format_time_with_user_timezone_cached(time, user, settings)

Formats a time with timezone using pre-loaded settings (cache-optimized).

get_date_examples(date)

Generates example formatted dates for all supported formats.

get_date_format_options()

Gets all supported date format options with dynamic examples.

get_time_examples(time)

Generates example formatted times for all supported formats.

get_time_format_options()

Gets all supported time format options with dynamic examples.

get_user_timezone(user)

Gets the effective timezone for a user.

get_user_timezone_cached(user, settings)

Gets the effective timezone for a user using cached system timezone.

# Functions

# format_date(date, format)

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"

# format_date_with_cached_settings(date, settings)

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"

# format_date_with_user_format(date)

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 selected

# format_date_with_user_timezone(date, user)

Formats 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 selected

# format_date_with_user_timezone_cached(date, user, settings)

Formats 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"

# format_datetime(datetime, format)

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"

# format_datetime_full(datetime, date_format, time_format)

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"

# format_datetime_full_with_user_format(datetime)

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"

# format_datetime_with_cached_settings(datetime, settings)

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"

# format_datetime_with_user_format(datetime)

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"

# format_datetime_with_user_timezone(datetime, user)

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 format

# format_datetime_with_user_timezone_cached(datetime, user, settings)

Formats 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"

# format_time(time, format)

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"

# format_time_with_cached_settings(time, settings)

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"

# format_time_with_user_format(time)

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 selected

# format_time_with_user_timezone(time, user)

Formats 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 selected

# format_time_with_user_timezone_cached(time, user, settings)

Formats 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"

# get_date_examples(date)

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"
    }

# get_date_format_options()

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
    ]

# get_time_examples(time)

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"
    }

# get_time_format_options()

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"}
    ]

# get_user_timezone(user)

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 default

# get_user_timezone_cached(user, settings)

Gets 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"