Displaying dates and times in Cotonti: A complete guide

Displaying Dates and Times in Cotonti: Complete Guide (Updated on 16.08.2026) 

Introduction 

Cotonti stores most dates and times as Unix timestamps – integers representing the number of seconds since midnight on January 1, 1970, UTC. This approach ensures uniformity, ease of comparison, and correct handling of time zones. To display dates in a human‑readable format and process user input, the system provides a set of functions and predefined formats.

This article covers all aspects of working with dates and times in Cotonti: basic functions, localization, template integration, and the datetime extra field type. The information is based on the current Cotonti source code (files system/extrafields.php, system/forms.php, system/functions.php, and the Russian language file lang/ru/main.ru.lang.php) and contains no assumptions.

Storing Dates and Times in Cotonti 

Virtually all date/time fields in the Cotonti database are stored as integers (int) – Unix timestamps in UTC. This applies to standard fields (e.g., user_regdate, page_date) as well as extra fields of type datetime.

An empty date value is usually stored as 0. This is important to remember when outputting: when formatted via standard functions, 0 may be converted to January 1, 1970, which is often undesirable. Therefore, always explicitly check the value before displaying it.

Storing data in UTC eliminates time‑zone issues: each user sees the date and time in their own local zone.

The cot_date() Function 

Signature:

function cot_date($format, $timestamp = null, $usertimezone = true)

This function is a wrapper around PHP's date() with additional support for localization and the current user's time zone.

Parameters

• $format – a format string. Can be a key from the $Ldt array (e.g., 'datetime_medium') or a standard PHP format ('Y-m-d H:i').
• $timestamp – a Unix timestamp. If not provided, the current time Cot::$sys['now'] is used.
• $usertimezone – a flag indicating whether to account for the user's time zone. Defaults to true.

Algorithm

1. If $timestamp is not provided, Cot::$sys['now'] is used.
2. The timestamp is cast to integer: (int)$timestamp.
3. If $usertimezone === true, the user's time zone offset (Cot::$usr['timezone'] * 3600) is added to the timestamp, converting the time from UTC to the user's local time.
4. If $format exists as a key in the $Ldt array, the corresponding format string is used; otherwise, $format itself is used.
5. PHP's date() is called with the resulting format string.
6. For non‑English languages, English day and month names are replaced with localized versions from the $L array.
7. The formatted string is returned.

Example

$timestamp = 1755345090; // 16.08.2026 14:31:30 UTC
echo cot_date('datetime_medium', $timestamp);
// Result for Russian: "16.08.2026 14:31" (adjusted to the user's time zone)

To display the date without time‑zone adjustment, pass false as the third parameter:

echo cot_date('Y-m-d H:i', $timestamp, false); // always UTC

Predefined Formats $Ldt

The $Ldt array is defined in the Cotonti language files. In the current version, it resides in lang/ru/main.ru.lang.php (and similar files for other languages). It contains named formats tailored to national date display conventions. Using keys from $Ldt is preferable to directly specifying PHP formats, as they automatically respect the locale.

The current table of formats for Russian (examples are for August 16, 2026, Sunday, 14:31:30):

Note: Week number W34 is calculated according to ISO‑8601 for 16.08.2026. If the week number belongs to the previous or next year, formats with o will show the corresponding year.

These formats may differ for other languages, so always refer to the corresponding language file (e.g., lang/en/main.en.lang.php).

Global Overriding of Formats

To change the date output format system‑wide, override elements of the $Ldt array. Simply add the desired lines in your theme's or plugin's language file, for example:

$Ldt['datetime_medium'] = 'Y-m-d H:i'; // override to MySQL‑style

After this, all calls to cot_date('datetime_medium', ...) will use the new format. It is recommended not to modify core files directly; instead, put overrides in theme‑specific files (theme.en.lang.php, theme.ru.lang.php, etc.) so that core updates do not overwrite your changes.

Using cot_date() in Templates

XTemplate in Cotonti supports callbacks. The syntax is:

{TAG|function('argument1', 'argument2', $this)}

$this refers to the tag's value. For example, if {PAGE_ROW_DATE_STAMP} contains a Unix timestamp, then:

{PAGE_ROW_DATE_STAMP|cot_date('d-m-Y', $this)}

will return the date in day-month-year format (e.g., 16-08-2026).

Using a Predefined Format

{PAGE_ROW_DATE_STAMP|cot_date('date_full', $this)}

Time Zone Handling

By default, cot_date respects the user's time zone. To display the time in UTC, pass false as the third parameter:

{PAGE_ROW_DATE_STAMP|cot_date('Y-m-d H:i', $this, false)}

However, in most cases local time is required, so false is rarely used.

Importing Dates: cot_import_date()

Signature:

function cot_import_date($name, $usertimezone = true, $returnarray = false, $source = 'P')

This function extracts date and time from incoming data (POST, GET, COOKIE) and converts them to a Unix timestamp.

Parameters

• $name – the field name (without square brackets if it is an array).
• $usertimezone – whether to adjust for the user's time zone. Default true.
• $returnarray – if true, returns an associative array with components (stamp, year, month, day, hour, minute).
• $source – data source: 'P' (POST), 'G' (GET), 'C' (COOKIE).

Algorithm

1. Checks for a custom function cot_import_date_custom() and the import.date hook.
2. Tries to retrieve an array from the source with keys year, month, day, hour, minute.
3. If the array is empty, attempts to read the value as a plain string (e.g., '2026-08-16 14:30').
4. If it is a string, converts it to a timestamp via cot_date2stamp().
5. If an array was received:
   • Checks if all components are null (empty date) → returns null.
   • If the condition ($month && $day && $year) || ($day && $minute) is true, builds a timestamp using cot_mktime($hour, $minute, 0, $month, $day, $year).
   • Otherwise, uses additional string and format fields if present.
6. If $usertimezone === true, subtracts the user's time zone offset: $timestamp -= Cot::$usr['timezone'] * 3600. This converts the time to UTC before saving.
7. Returns the timestamp (or an array if $returnarray = true).

Example

$myDate = cot_import_date('rdate', true, false, 'P');
// $myDate — Unix timestamp in UTC or null if date not set

Building the Date Form: cot_selectbox_date()

Signature:

function cot_selectbox_date($utime, $mode = 'long', $name = '', $max_year = 2030, $min_year = 2000, $usertimezone = true, $custom_rc = '')

This function generates a set of dropdown lists for selecting date and time.

Parameters

• $utime – the current value (timestamp) or 0 for an empty date.
• $mode – 'long' (year, month, day, hour, minute) or 'short' (date only).
• $name – the base field name (e.g., rxtra_x200_last_promotion).
• $max_year, $min_year – year boundaries.
• $usertimezone – whether to account for the user's time zone when displaying. Default true.
• $custom_rc – the name of a custom resource template.

Behaviour

• If $utime == 0, lists are displayed empty (or restored from the buffer).
• If cot_selectbox_date_custom() is defined, it is used instead of the standard function.
• The hook form.date allows complete override of the output.
• Final field names are built as $name.'[year]', $name.'[month]', $name.'[day]', $name.'[hour]', $name.'[minute]'.

The function automatically adjusts the displayed time to the user's time zone if $usertimezone = true and $utime > 0.

The datetime Extra Field Type

Extra fields of type datetime are fully integrated into the system described above. They store values in the database as int DEFAULT '0' and use the same functions for form building, import, and output.

Field Parameters

The field_params field for datetime contains a string min,max,format.

• min – minimum year. If ≤ 0, 2000 is used.
• max – maximum year. If ≤ 0, 2030 is used.
• format – output format (a key from $Ldt or a PHP format string). If empty, the raw timestamp is returned on output.

Example: "2000,2030,datetime_medium".

Building the Form

In the cot_build_extrafields() function (case 'datetime'):

1. min, max, format are parsed.
2. Relative dates are handled: if the value starts with + or -, it is interpreted as an offset in seconds from the current time $sys['now']. For example, +86400 means tomorrow.
3. cot_selectbox_date((int)$data, 'long', $name, (int)$max, (int)$min, true, $extrafield['field_html']) is called.

The result is a form containing five dropdowns: year, month, day, hour, minute.

Import and Saving

When the form is submitted, cot_import_extrafields() is called (case 'datetime'):

1. Calls cot_import_date($inputname, true, false, $source).
2. If the result is null, sets $import = 0.
3. If min or max are set (>0), checks the year of the resulting date and adjusts it if necessary, preserving other components.
4. If the field is required and the final value is 0, triggers an error.

The final value is a Unix timestamp in UTC.

Outputting Values

For output, cot_build_extrafields_data() is used. If format is set in the field parameters, cot_date($format, $value) is called; otherwise the raw timestamp is returned.

Time Zones

• On input – the time is adjusted according to the time zone of the user filling the form (offset subtracted) and saved as UTC.
• On output – the time is adjusted according to the time zone of the user viewing the page (offset added) and displayed in local time.

Helper Functions

cot_mktime()

Creates a Unix timestamp from date components. If no arguments are passed, the current values are used.

function cot_mktime($hour = false, $minute = false, $second = false, $month = false, $date = false, $year = false)

cot_date2stamp()

Converts a date string to a Unix timestamp.

• If the format is not specified or equals 'auto', strtotime() is used.
• Otherwise, date_parse_from_format() is used.
• Returns null for empty or zero dates (e.g., '0000-00-00').

cot_stamp2date()

Converts a timestamp to a string in Y-m-d format (MySQL date).

The _VALUE Suffix in the Context of Dates

When generating tags for datetime extra fields, the following suffixes are typically used:

• _VALUE – the raw value from the database, i.e., a Unix timestamp (integer) or 0 if no date is set. Used for checks and comparisons.
• _TITLE – the field label.
• The plain tag (without suffix) – the formatted value if a format is set in the field parameters. For an empty date (0), such a tag may return a string like "January 1, 1970", so always use _VALUE to check for existence.

Example for datetime

<!-- IF {USERS_DETAILS_XTRA_X200_LAST_PROMOTION_VALUE} -->
    <div class="contact-label">{USERS_DETAILS_XTRA_X200_LAST_PROMOTION_TITLE}</div>
    <div class="contact-value">{USERS_DETAILS_XTRA_X200_LAST_PROMOTION}</div>
<!-- ENDIF -->

Here the condition <!-- IF {TAG_VALUE} --> is true only if the timestamp is not 0, i.e., a date has actually been selected.

Usage Examples in Plugins and Modules

Registering a datetime Extra Field

cot_extrafield_add(
    'users',
    'my_event_datetime',
    'datetime',
    '',
    '',
    '',
    false,
    'HTML',
    'Event date',
    '2000,2030,datetime_medium'
);

Saving from a Form

$extrafield = [/* get field description */];
$oldValue = $existing['user_my_event_datetime'] ?? 0;
$newValue = cot_import_extrafields('rxtra_my_event_datetime', $extrafield, 'P', $oldValue, 'xtra_');
// $newValue — Unix timestamp in UTC

Output in Template

<!-- IF {USERS_DETAILS_XTRA_X200_LAST_PROMOTION_VALUE} -->
    <div class="contact-label">{USERS_DETAILS_XTRA_X200_LAST_PROMOTION_TITLE}</div>
    <div class="contact-value">{USERS_DETAILS_XTRA_X200_LAST_PROMOTION}</div>
<!-- ENDIF -->

Or with a direct call to cot_date:

{PAGE_ROW_DATE_STAMP|cot_date('datetime_full', $this)}

Conclusion

Cotonti provides a powerful and flexible toolkit for working with dates and times. With cot_date(), cot_import_date(), cot_selectbox_date(), and the predefined $Ldt formats, developers can easily display dates in any required format, respecting localization and time zones. The datetime extra field type is fully integrated into this system, ensuring correct handling of user input. When using these in templates, always remember to check values via the _VALUE tag to avoid displaying empty dates as "January 1, 1970".

Back to top