Skip to main content

Full Clock Format List

The Clock functionality in DTO makes it easy to work with dates and times using PHP’s DateTime object under the hood. Whether you're formatting timestamps, comparing dates, or localizing output, these built-in methods provide a clean and consistent approach for handling temporal data.

How It Works​

With Traverse Collection​

echo $event->starts_at->clockSetLocale("sv_SE")->clockFormat("l, j F");
// Result: torsdag, 1 maj

As Singleton Helper​

use MaplePHP\DTO\Format\Clock;

echo Clock::value("2025-05-01 14:30")->clockSetTimezone("UTC")->format("Y-m-d H:i");
// Result: 2025-05-01 14:30

For more transformation options like clockIsToday, clockWeekday, and clockToTimezone, check the Transformation section in the navigation below.

Full Feature List​

setLocale

The setLocale method sets the locale used for translating month and weekday names. It falls back to PHP’s IntlDateFormatter if static translations are not available.

Arguments

Takes a required $localeCode string (e.g., 'sv_SE', 'en_US') to define the language/region for date formatting.

$event = Traverse::value(["starts_at" => "2025-03-20"]);

echo $event->starts_at->clockSetLocale("sv_SE")->clockFormat("l, j F");  

// Result: torsdag, 20 mars

setDefaultLocale

The setDefaultLocale method sets a global default locale used for translating month and weekday names if no local locale is specified.

Arguments

Takes a required $localeCode string (e.g., 'sv_SE', 'en_US') to set as the default language/region.

Clock::setDefaultLocale("sv_SE");

$event = Traverse::value(["starts_at" => "2025-03-20"]);

echo $event->starts_at->clockFormat("l, j F");  

// Result: torsdag, 20 mars

setTimezone

The setTimezone method sets the timezone of the DateTime object.

Arguments

Takes a $timezone as either a DateTimeZone instance or a string (e.g., 'Europe/Stockholm').

$event = Traverse::value(["starts_at" => "2025-03-20 14:30:00"]);

echo $event->starts_at->clockSetTimezone("UTC")->clockFormat("Y-m-d H:i");  

// Result: 2025-03-20 13:30

setDefaultTimezone

The setDefaultTimezone method sets the default timezone that will be used when no specific timezone is set on the DateTime object.

Arguments

Takes a $timezone as either a string (e.g., 'UTC', 'Europe/Stockholm') or a DateTimeZone instance.

Clock::setDefaultTimezone("Europe/Stockholm");

$event = Traverse::value(["starts_at" => "2025-03-20 14:30:00"]);

echo $event->starts_at->clockFormat("Y-m-d H:i");  

// Result: 2025-03-20 14:30

format

The format method returns the date formatted as a string based on the given format. It also supports locale-based translation of month and weekday names if available.

Arguments

Takes an optional $format string using PHP's date format syntax (default: 'Y-m-d H:i:s'), and an optional $locale for localized output.

$event = Traverse::value(["starts_at" => "2025-05-01 14:30"]);

echo $event->starts_at->clockFormat("Y-m-d H:i");  

// Result: 2025-05-01 14:30

iso

The iso method returns the date and time in ISO 8601 format (e.g., 2025-03-20T14:30:00+01:00).

$event = Traverse::value(["starts_at" => "2025-03-20 14:30:00"]);

echo $event->starts_at->clockIso();  

// Result: 2025-03-20T14:30:00+01:00

rfc

The rfc method returns the date and time formatted according to RFC 2822 (e.g., Thu, 20 Mar 2025 14:30:00 +0100).

$event = Traverse::value(["starts_at" => "2025-03-20 14:30:00"]);

echo $event->starts_at->clockRfc();  

// Result: Thu, 20 Mar 2025 14:30:00 +0100

dateTime

The dateTime method returns the full date and time in Y-m-d H:i:s format.

$event = Traverse::value(["starts_at" => "2025-03-20 14:30:00"]);

echo $event->starts_at->clockDateTime();  

// Result: 2025-03-20 14:30:00

date

The date method returns only the date portion of the DateTime object in Y-m-d format.

$event = Traverse::value(["starts_at" => "2025-05-01 14:30"]);

echo $event->starts_at->clockDate();  

// Result: 2025-05-01

timestamp

The timestamp method returns the Unix timestamp representation of the date and time.

$event = Traverse::value(["starts_at" => "2025-03-20 14:30:00"]);

echo $event->starts_at->clockTimestamp();  

// Result: 1742471400

year

The year method returns the year of the date. You can choose between full (e.g., 2025) or shorthand (e.g., 25) format.

Arguments

Takes an optional $shorthand boolean to return the year in two-digit format if true (default: false).

$event = Traverse::value(["starts_at" => "2025-03-20"]);

echo $event->starts_at->clockYear();  

// Result: 2025

month

The month method returns the numeric month of the date, with leading zero (e.g., 03 for March).

$event = Traverse::value(["starts_at" => "2025-03-20"]);

echo $event->starts_at->clockMonth();  

// Result: 03

monthName

The monthName method returns the full name of the month (e.g., January).

$event = Traverse::value(["starts_at" => "2025-01-15"]);

echo $event->starts_at->clockMonthName();  

// Result: January

shortMonthName

The shortMonthName method returns the abbreviated name of the month (e.g., Jan).

$event = Traverse::value(["starts_at" => "2025-01-15"]);

echo $event->starts_at->clockShortMonthName();  

// Result: Jan

day

The day method returns the day of the month with leading zero (e.g., 05).

$event = Traverse::value(["starts_at" => "2025-03-05"]);

echo $event->starts_at->clockDay();  

// Result: 05

dayOfWeek

The dayOfWeek method returns the day of the week as a number (1 for Monday through 7 for Sunday).

$event = Traverse::value(["starts_at" => "2025-03-20"]);

echo $event->starts_at->clockDayOfWeek();  

// Result: 4

time

The time method returns the time portion of the DateTime object in H:i format (24-hour clock).

$event = Traverse::value(["starts_at" => "2025-05-01 14:30"]);

echo $event->starts_at->clockTime();  

// Result: 14:30

time12Hour

The time12Hour method returns the time in 12-hour format with an AM/PM suffix (e.g., 02:30 PM).

$event = Traverse::value(["starts_at" => "2025-03-20 14:30:00"]);

echo $event->starts_at->clockTime12Hour();  

// Result: 02:30 PM

seconds

The seconds method returns the seconds portion of the time, including leading zeros (e.g., 05).

$event = Traverse::value(["starts_at" => "2025-05-01 14:30:05"]);

echo $event->starts_at->clockSeconds();  

// Result: 05

weekday

The weekday method returns the full name of the weekday (e.g., Monday).

$event = Traverse::value(["starts_at" => "2025-03-17"]);

echo $event->starts_at->clockWeekday();  

// Result: Monday

shortWeekday

The shortWeekday method returns the abbreviated name of the weekday (e.g., Mon).

$event = Traverse::value(["starts_at" => "2025-03-17"]);

echo $event->starts_at->clockShortWeekday();  

// Result: Mon

weekNumber

The weekNumber method returns the ISO 8601 week number of the year.

$event = Traverse::value(["starts_at" => "2025-01-01"]);

echo $event->starts_at->clockWeekNumber();  

// Result: 1

isLeapYear

The isLeapYear method checks if the year is a leap year and returns a boolean value.

$event = Traverse::value(["starts_at" => "2024-03-01"]);

echo $event->starts_at->clockIsLeapYear();  

// Result: true

diffInDays

The diffInDays method returns the number of days between the given date and today. The result is negative for past dates and positive for future dates.

$event = Traverse::value(["starts_at" => "2025-04-01"]);

echo $event->starts_at->clockDiffInDays();  

// Result: 10

isToday

The isToday method checks if the given date is today and returns a boolean value.

$event = Traverse::value(["starts_at" => date("Y-m-d H:i:s")]);

echo $event->starts_at->clockIsToday();  

// Result: true