PHP Luminova: Immutable Date & Time Module

Time class is a powerful extension of PHP's native DateTimeImmutable class, designed to enhance date and time operations within your application. By extending the functionality of the core DateTimeImmutable class, the Luminova's Time class offers range of additional features and convenience methods, making it easier to manipulate, format, and work with dates and times in your project.

Time class serves as a valuable addition to the Luminova's PHP developer's toolkit, to work more efficiently and effectively with date and time data, ultimately contributing to the reliability of your application development.

• Class namespace: \Luminova\Time\Time
• Parent class: DateTimeImmutable

Methods

constructor

Time constructor.

public __construct(string|null $datetime = null, \DateTimeZone|string|null $timezone = null): mixed

Parameters:

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if error occurs during DateTimeImmutable object construction.

timezone

Converts string to timezone instance if not already a timezone instance.

public static timezone(\DateTimeZone|string $timezone): \DateTimeZone

Parameters:

Return Value:

\DateTimeZone - The timezone instance.

now

Returns current DateTime instance with the timezone set.

public static now(\DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - New DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurs.

parse

Returns a new Time instance while parsing a datetime string.

public static parse(string $datetime, \DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - New DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurs.

today

Return a new time with the time set to midnight.

public static today(\DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

yesterday

Returns an instance set to midnight yesterday morning.

public static yesterday(\DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

setTimezone

Set the TimeZone associated with the DateTime, and returns a new instance with the updated timezone.

public setTimezone(\DateTimeZone|string $timezone): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

getYear

Gets year from the current datetime format.

public getYear(): string

Return Value:

string - Return year

getMonth

Gets month from the current datetime format.

public getMonth(): string

Return Value:

string - Return month.

getDay

Gets day from the current datetime format.

public getDay(): string

Return Value:

string - Return day of the month

getHour

Gets hour (in 24-hour format), from the current datetime format.

public getHour(): string

Return Value:

string - Return hours of the day.

getMinute

Gets minutes from the current datetime format.

public getMinute(): string

Return Value:

string - Return minutes.

getSecond

Gets seconds from the current datetime format.

public getSecond(): string

Return Value:

string - Return seconds.

getDayOfYear

Gets day of the year, from the current datetime format.

public getDayOfYear(): string

Return Value:

string - Return day of the year.

getWeekOfMonth

Gets week of the month, from the current datetime format.

public getWeekOfMonth(): string

Return Value:

string - Return week of the month.

getWeekOfYear

Gets week of the year from the current datetime format.

public getWeekOfYear(): string

Return Value:

string - Return week of the year.

getDayOfWeek

Gets week of the day from the current datetime format.

public getDayOfWeek(): string

Return Value:

string - Return day of the week.

getQuarter

Gets quarter of the year, from the current datetime format.

public getQuarter(): string

Return Value:

string - Return quarter of the year.

datetime

Return string datetime of this format 'yyyy-mm-dd H:i:s'.

public static datetime(null|\DateTimeZone|string $timezone = 'UTC'): string

Parameters:

Return Value:

string - Returns datetime string.

isDaylight

Determine if the current time is already in daylight savings.

public isDaylight(): bool

Return Value:

bool - Return true if the current time is already in daylight saving, false otherwise.

isSystemTimezone

Check whether the passed timezone is the same as the application timezone.

public isSystemTimezone(): bool

Return Value:

bool - true if the passed timezone is the same as the local timezone false otherwise.

isUtc

Returns boolean whether object is in UTC.

public isUtc(): bool

Return Value:

bool - Whether the timezone offset is UTC.

getTimezoneName

Returns the name of the current timezone.

public getTimezoneName(): string

Return Value:

string - The name of the current timezone.

getMaxAge

Calculates the maximum age in seconds until a given timestamp.

public getMaxAge(int $timestamp): int

Parameters:

Return Value:

int - Return the number of seconds from the current timestamp to the given timestamp.

getInstanceUtc

Returns Datetime instance of UTC timezone.

public getInstanceUtc(\DateTimeInterface|\Luminova\Time\Time|string $datetime, ?string $timezone = null): \DateTime

Parameters:

Return Value:

\DateTime - Return new datetime instance of UTC timezone.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

toFormat

Returns a formatted datetime to your preferred format.

public toFormat(null|string $format = null): false|string

Parameters:

Return Value:

false|string - Formatted datetime string otherwise false.

toTime

Returns a formatted time string (ex. 17:17:17).

public toTime(): string

Return Value:

string - Formatted time string otherwise false.

toDatetime

Converts the current instance to a mutable DateTime object.

public toDatetime(): \DateTime

Return Value:

\DateTime - Return new datetime object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

fromInstance

Takes an instance of DateTimeInterface and returns an instance of Time with it's same values.

public static fromInstance(\DateTimeInterface $datetime): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

fromTimestamp

Returns a new instance with the datetime set based on the provided UNIX timestamp.

public static fromTimestamp(int $timestamp, \DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

fromDate

Returns a new instance based on the year, month and day. If any of those three are left empty, will default to the current value.

public static fromDate(int|null $year = null, int|null $month = null, int|null $day = null, \DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

fromTime

Returns a new instance with the date set to today, and the time set to the values passed in.

public static fromTime(int|null $hour = null, int|null $minutes = null, int|null $seconds = null, \DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

fromRelative

Returns a new datetime instance from a relative time format.

public static fromRelative(string $datetime, \DateTimeZone|string|null $timezone = null): string

Parameters:

Return Value:

string - Return formatted DateTime string.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if invalid relative time format was passed.

createFrom

Returns a new instance with the date time values individually set.

public static createFrom(int|null $year = null, int|null $month = null, int|null $day = null, int|null $hour = null, int|null $minutes = null, int|null $seconds = null, \DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

tomorrow

Returns an instance set to midnight tomorrow morning.

public static tomorrow(\DateTimeZone|string|null $timezone = null): self

Parameters:

Return Value:

self - Return new DateTimeImmutable object.

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

fromFormat

Create new DateTimeImmutable object formatted according to the specified format.

public static fromFormat(string $format, string $datetime, \DateTimeZone|string|null $timezone = null): \DateTimeImmutable|false

Parameters:

Return Value:

\DateTimeImmutable|false - Returns new DateTimeImmutable false otherwise

Throws:

• \Luminova\Exceptions\DatetimeException - Throws if any error occurred.

calendar

Returns an array representation of the given calendar month.

public static calendar(?string $month = null, ?string $year = null, \DateTimeZone|string|null $timezone = null): array<int,mixed>

The array values are timestamps which allow you to easily format.

Parameters:

Return Value:

array<int,mixed> - $calendar Calendar values.

days

Get an array of dates for each day in a specific month.

public static days(string|int|null $month = null, string|int|null $year = null, string $format = 'd-M-Y'): array<int,string>

Parameters:

Return Value:

array<int,string> - An array of dates within the specified month.

months

Get an array of months for each month in a specific year.

public static months(string $format = 'M'): array<int,string>

Parameters:

Return Value:

array<int,string> - An array of month within the specified year.

years

Generate a list of years between a start and end year.

public static years(int|string|null $start = null, int|string|null $end = null): array<int,int>

Parameters:

Return Value:

array<int,int> - List of years.

hours

Get a list of time hours in 12-hour format with customizable intervals.

public static hours(int $interval = 30): array<int,string>

Parameters:

Return Value:

array<int,string> - An array of time hours.

ago

Convert datetime to relative a human-readable representation of the time elapsed since the given datetime.

public static ago(string|int|\Luminova\Time\Time|\DateTimeImmutable $datetime, bool $full = false, \DateTimeZone|string|null $timezone = null): string

Parameters:

Return Value:

string - A string representing the time elapsed since the given datetime, in human-readable format.

If a string is provided, it must be a valid datetime string or time string.

agoToDatetime

Convert relative time ago to datetime instance.

public static agoToDatetime(string $ago, \DateTimeZone|string|null $timezone = null): \DateTime

Parameters:

Return Value:

\DateTime - Return new datetime instance.

Throws:

• \Luminova\Exceptions\DateTimeException - If invalid time unit was found in the ago format.

passed

Check if a certain amount of minutes has passed since the given timestamp.

public static passed(string|int|\Luminova\Time\Time|\DateTimeImmutable $datetime, int $minutes, null|\DateTimeZone|string $timezone = 'UTC'): bool

Parameters:

Return Value:

bool - True if the specified minutes have passed, false otherwise.

Throws:

• \Luminova\Exceptions\DateTimeException - If invalid datetime was passed.

suffix

Get the suffix for a given day (e.g., 1st, 2nd, 3rd, 4th).

public static suffix(string|int $day): string

Parameters:

Return Value:

string - The day with its appropriate suffix.

isRelative

Check if time string has a relative time keywords.

public static isRelative(string $datetime): bool

Parameters:

Return Value:

bool - True if the string contains relative time keywords otherwise, false.

isAgo

Check if time string has a human-readable relative time keywords from ago method.

public static isAgo(string $datetime): bool

Parameters:

Return Value:

bool - True if the string contains relative time keywords otherwise, false.

isAbsolute

Check if time string is a valid absolute time string.

public static isAbsolute(string $datetime): bool

Parameters:

Return Value:

bool - True if the string contains absolute time time otherwise, false.