Format Datetime

Property	Value
description	Preset-based datetime formatting for templates, Bricks, and child-theme overrides.
tags	doc, mac-core, utility, datetime
rating

Human: 4 - AI-assisted (low impact)

Some AI used for minor parts (phrasing, ideas), but nothing critical. Fully reviewed.

Overview

mac_format_datetime() is the main public datetime helper in MAC Core.

It formats preset-based date and time data for:

• templates
• Bricks echo functions
• light site-level helper code

Signature:

mac_format_datetime(?string $preset = null, ?string $view = null, int|string|null $post_id = null): string

Built-In Defaults

Default config:

• default preset: event
• default view: plain

If mac_format_datetime() is called with blank arguments, the helper resolves those defaults first.

Built-In Event Preset

The shipped preset maps these field names:

Key	Field
start_datetime	event_start_datetime
end_datetime	event_end_datetime
start_date	event_start_date
end_date	event_end_date
start_time	event_start_time
end_time	event_end_time
timezone	event_timezone

Default input formats:

• datetime: Y-m-d H:i:s
• date: Y-m-d
• time: H:i

Default output formats:

• use the site date and time format settings when the preset and view do not override them

Built-In Views

The shipped views are:

• plain
• plain_relative
• plain_diff
• plain_with_timezone
• plain_relative_with_timezone
• html
• html_relative
• html_with_timezone
• html_relative_with_timezone
• html_diff
• attr

Return types:

• plain -> text output
• html -> wrapped HTML with <time> markup
• attr -> machine datetime string for attribute usage

Usage Examples

<?php

echo mac_format_datetime();
echo mac_format_datetime( 'event', 'plain' );
echo mac_format_datetime( 'event', 'html' );
echo mac_format_datetime( 'event', 'attr' );
echo mac_format_datetime( 'event', 'plain_with_timezone', get_the_ID() );

Extending It in a Child Theme

The supported extension hooks are:

• mac_core_format_datetime_config
• mac_core_format_datetime_presets
• mac_core_format_datetime_views

Example:

<?php

add_filter(
	'mac_core_format_datetime_presets',
	function ( array $presets ): array {
		$presets['launch'] = [
			'start_date' => 'launch_date',
			'end_date'   => 'launch_end_date',
			'start_time' => 'launch_time',
			'timezone'   => 'launch_timezone',

			'input_date_format' => 'Y-m-d',
			'input_time_format' => 'H:i',

			'output_date_format' => 'F j, Y',
			'output_time_format' => 'g:i a',
		];

		return $presets;
	},
	10,
	4
);

add_filter(
	'mac_core_format_datetime_views',
	function ( array $views ): array {
		$views['plain_short'] = [
			'return'             => 'plain',
			'output_date_format' => 'Y/m/d',
		];

		return $views;
	},
	10,
	4
);

add_filter(
	'mac_core_format_datetime_config',
	function ( array $config ): array {
		$config['default_preset'] = 'launch';
		$config['default_view']   = 'plain_short';

		return $config;
	},
	10,
	4
);

Then use:

<?php

echo mac_format_datetime();
echo mac_format_datetime( 'launch', 'plain_short' );

Failure Behavior

mac_format_datetime() fails safely and returns an empty string when:

• the resolved preset does not exist
• the resolved view does not exist
• no usable post context can be resolved
• the underlying date or time values cannot be parsed into a valid start point

Filter safety behavior:

• invalid non-array payloads for presets and views fall back to the built-in static definitions
• invalid non-array config payloads fall back to the built-in config
• if a filter changes the default preset or view to a missing key, output resolves to an empty string rather than unsafe fallback markup

When to Use It

Use FormatDatetime when the problem is:

• repeated across multiple builds
• based on predictable field mappings
• mostly formatting and output, not business logic

If the formatting rule is highly specific to one project or one content model, keep that logic in the child theme unless it clearly deserves to become a shared preset or view.