README

Lightweight date utilities for WordPress focusing on UTC storage and local display without external dependencies.

Features

Zero Dependencies - Uses only WordPress core and PHP built-ins
UTC Storage - Store dates safely in UTC for database
Local Display - Convert to site timezone for display
Date Ranges - 12 essential predefined ranges (today, last week, last 90 days, etc.)
Date Math - Add/subtract days, hours, months with precision
Business Logic - Weekend/business day checking, age calculation
Subscription Periods - Handle billing cycles with Stripe compatibility
Formatting - WordPress date/time settings with i18n support
Validation - Date format checking, expiration logic, freshness checks
Database Helpers - Query builders for date ranges
Lightweight - ~450 lines vs thousands with Carbon
WordPress Native - Built on wp_date(), get_gmt_from_date(), etc.

Installation

composer require arraypress/wp-date-utils

Basic Usage

use ArrayPress\DateUtils\Dates;

// Current times
$utc_now   = Dates::now_utc();        // For database storage
$local_now = Dates::now_local();      // For display

// Convert between UTC and local
$utc   = Dates::to_utc( $user_input );           // Store in DB
$local = Dates::to_local( $database_value );     // Display to user

// Format dates
echo Dates::format( $utc_date );                 // Uses WP settings
echo Dates::format( $utc_date, 'date' );         // Date only
echo Dates::format( $utc_date, 'time' );         // Time only

// Human-readable
echo Dates::human_diff( $utc_date );  // "2 hours ago"

// Format with empty handling
echo Dates::format_or_empty( $date );            // Shows "—" if empty
echo Dates::format_or_empty( $date, 'Never', 'human' );  // "Never" for empty dates

Date Ranges

// Get predefined ranges (returns UTC start/end)
$range = Dates::get_range( 'today' );
$range = Dates::get_range( 'last_week' );
$range = Dates::get_range( 'last_30_days' );
$range = Dates::get_range( 'year_to_date' );

// Essential ranges available:
// today, yesterday
// this_week, last_week
// this_month, last_month
// this_year, last_year
// last_7_days, last_30_days, last_90_days
// year_to_date

// Returns: ['start' => '2025-01-01 00:00:00', 'end' => '2025-01-31 23:59:59']

// Ranges calculate in local timezone by default
$today = Dates::get_range( 'today' );  // Today in site timezone, returned as UTC

// Or use pure UTC calculation (for rolling windows)
$last_30 = Dates::get_range( 'last_30_days', false );  // Pure UTC

Date Math

// Add time (uses precise DateTime for months/years)
$future = Dates::add( $utc_date, 7, 'days' );
$future = Dates::add( $utc_date, 2, 'hours' );
$future = Dates::add( $utc_date, 1, 'months' );   // Precise month calculation
$future = Dates::add( $utc_date, 1, 'years' );    // Handles leap years

// Subtract time
$past = Dates::subtract( $utc_date, 30, 'days' );
$past = Dates::subtract( $utc_date, 6, 'months' );

// Direct month/year arithmetic
$next_month = Dates::add_months( $utc_date, 1 );
$next_year = Dates::add_years( $utc_date, 1 );

// Get difference
$days  = Dates::diff( $date1, $date2, 'days' );
$hours = Dates::diff( $date1, $date2, 'hours' );

// Get elapsed time
$hours_ago = Dates::elapsed( $utc_date, 'hours' );  // null if invalid

// Calculate expiration
$expires = Dates::calculate_expiration( 30, 'days' );
$expires = Dates::calculate_expiration( 1, 'years' );

Validation & Checks

// Date validation
if ( Dates::is_valid( $date_string ) ) {}
if ( Dates::is_format( $date, 'Y-m-d' ) ) {}

// Date checks
if ( Dates::is_expired( $utc_date ) ) {}
if ( Dates::is_expired( $utc_date, 24 ) ) {}  // With 24-hour grace period
if ( Dates::is_future( $utc_date ) ) {}
if ( Dates::is_past( $utc_date ) ) {}
if ( Dates::is_zero( $date ) ) {}  // Check for 0000-00-00
if ( Dates::in_range( $date, $start, $end ) ) {}

// Freshness checks
if ( Dates::is_stale( $last_sync, 24, 'hours' ) ) {
    // Data is older than 24 hours or empty
}

if ( Dates::is_fresh( $cache_time, 1, 'hours' ) ) {
    // Cache is less than 1 hour old and valid
}

// Age calculation
$age = Dates::get_age( $birth_date_utc );

Business Logic

// Weekend/business day checking
if ( Dates::is_weekend( $utc_date ) ) {}
if ( Dates::is_business_day( $utc_date ) ) {}

// Custom business days (1=Mon, 7=Sun)
$custom_days = [1, 2, 3, 4, 5, 6]; // Mon-Sat
if ( Dates::is_business_day( $utc_date, $custom_days ) ) {}

// Get next business day
$next = Dates::next_business_day( $utc_date );
$next = Dates::next_business_day( $utc_date, [1, 2, 3, 4, 5] );

Date Boundaries

// Get start/end of day
$start = Dates::start_of_day( $utc_date );  // "2025-01-15 00:00:00"
$end = Dates::end_of_day( $utc_date );      // "2025-01-15 23:59:59"

Subscriptions & Billing

// Calculate next billing date (uses precise month/year arithmetic)
$next = Dates::next_billing( $last_payment, 'monthly' );
$next = Dates::next_billing( $last_payment, 'yearly' );
$next = Dates::next_billing( $last_payment, 'every_3_months' );

// Stripe-compatible periods
$periods = Dates::get_period_options();
// Returns: daily, weekly, monthly, every_3_months, every_6_months, yearly

// Include custom option for UI
$periods = Dates::get_period_options( true );  // Adds 'custom' option

// Convert to Stripe format
$stripe = Dates::get_stripe_interval( 'every_3_months' );
// Returns: ['interval' => 'month', 'interval_count' => 3]

Timestamp Conversion

// Convert Unix timestamp to MySQL
$mysql_date = Dates::timestamp_to_mysql( $timestamp );

// Convert MySQL to timestamp
$timestamp = Dates::to_timestamp( $mysql_date );

Admin Display

// Format for admin with relative time
echo Dates::format_admin( $utc_date );
// Outputs: "Jan 15, 2025 10:30 AM<br><small>2 hours ago</small>"

Database Integration

// Build date range queries
$query = Dates::build_date_query( 'created_at', $start_local, $end_local );

$results = $wpdb->get_results( $wpdb->prepare(
    "SELECT * FROM orders WHERE {$query['sql']}",
    ...$query['values']
) );

Real-World Examples

Storing User Input

// User submits date in their timezone
$user_date = $_POST['event_date'];  // "2025-01-15 14:30:00"

// Convert to UTC for database
$utc_date = Dates::to_utc( $user_date );

// Store in database
$wpdb->insert( $table, [ 'event_date' => $utc_date ] );

Displaying Dates

// Get from database (stored as UTC)
$event = $wpdb->get_row( "SELECT * FROM events WHERE id = 1" );

// Display in user's timezone
echo Dates::format( $event->event_date );      // "Jan 15, 2025 2:30 PM"
echo Dates::human_diff( $event->created_at );  // "3 days ago"

// Display with empty handling
echo Dates::format_or_empty( $event->deleted_at, 'Not deleted', 'human' );

Date Range Queries

// User selects "Last 30 Days" 
$range = Dates::get_range( 'last_30_days' );

// Query database with proper UTC dates
$results = $wpdb->get_results( $wpdb->prepare(
    "SELECT * FROM orders WHERE created_at BETWEEN %s AND %s",
    $range['start'],
    $range['end']
) );

Data Freshness Checking

class API_Cache {
    public function get_data() {
        $cached_at = get_option( 'api_cache_time' );
        
        // Check if cache is stale (older than 1 hour)
        if ( Dates::is_stale( $cached_at, 1, 'hours' ) ) {
            $data = $this->fetch_from_api();
            update_option( 'api_cache_time', Dates::now_utc() );
            return $data;
        }
        
        return get_option( 'api_cache_data' );
    }
}

Subscription Management

// Calculate next billing with Stripe-compatible periods
$subscription = get_subscription( $user_id );
$next_billing = Dates::next_billing( $subscription->last_payment, 'every_3_months' );

// Convert for Stripe API
$stripe_interval = Dates::get_stripe_interval( 'every_3_months' );
\Stripe\Subscription::create([
    'customer' => $customer_id,
    'items' => [['price' => $price_id]],
    'recurring' => $stripe_interval
]);

// Check if expired with grace period
if ( Dates::is_expired( $subscription->expires_at, 72 ) ) {  // 72-hour grace
    cancel_subscription( $user_id );
}

Admin Table Column

public function column_created( $item ) {
    // Properly converts UTC to local and formats
    return Dates::format( $item['created_at'] );
    
    // Or with admin formatting (includes relative time)
    return Dates::format_admin( $item['created_at'] );
}

public function column_last_sync( $item ) {
    // Shows "Never" for empty dates
    return Dates::format_or_empty( $item['last_sync_at'], 'Never', 'human' );
}

Method Reference

Core Operations

now_utc() - Current UTC time
now_local() - Current local time
to_utc() - Convert local to UTC
to_local() - Convert UTC to local

Date Math

add() - Add time units
subtract() - Subtract time units
add_months() - Precise month addition
add_years() - Precise year addition
diff() - Get difference between dates
elapsed() - Get elapsed time since date

Formatting

format() - WordPress format with i18n
human_diff() - Human readable difference
format_admin() - Admin display with relative time
format_or_empty() - Format with empty value handling

Validation

is_valid() - Validate date string
is_format() - Check specific format
is_expired() - Check expiration with grace period
is_future() / is_past() - Time comparisons
is_zero() - Check for empty/zero dates
in_range() - Check if date within range
is_stale() - Check if older than threshold
is_fresh() - Check if within threshold

Business Logic

is_weekend() / is_business_day() - Day type checking
next_business_day() - Skip to next business day
get_age() - Calculate age from birth date

Date Ranges

get_range() - Get predefined ranges
range_to_utc() - Convert local range to UTC
start_of_day() / end_of_day() - Day boundaries

Subscription & Billing

next_billing() - Calculate next billing date
get_period_options() - Get period dropdown options
get_stripe_interval() - Convert to Stripe format
calculate_expiration() - Calculate future expiration

Utilities

timestamp_to_mysql() - Unix timestamp to MySQL
to_timestamp() - MySQL to Unix timestamp
build_date_query() - Database query builder
get_range_options() - Get range dropdown options

Why Not Carbon?

This library is intentionally lightweight:

Performance: No heavy dependency loading
Size: ~450 lines vs Carbon's thousands
Simplicity: Does exactly what WordPress needs
Native: Uses WordPress's own date functions
Sufficient: Covers 99% of WordPress date needs
Maintenance: Fewer dependencies to manage

arraypress / wp-date-utils

Maintainers

Details

README

Features

Installation

Basic Usage

Date Ranges

Date Math

Validation & Checks

Business Logic

Date Boundaries

Subscriptions & Billing

Timestamp Conversion

Admin Display

Database Integration

Real-World Examples

Storing User Input

Displaying Dates

Date Range Queries

Data Freshness Checking

Subscription Management

Admin Table Column

Method Reference

Core Operations

Date Math

Formatting

Validation

Business Logic

Date Ranges

Subscription & Billing

Utilities

Why Not Carbon?

Requirements

License

Support