Luminova Framework

PHP Luminova: Immutable Date & Time Module

Last updated: 2024-08-28 22:54:32

The Luminova Time class is an extension of PHP DateTimeImmutable`and provides additional functionality and convenience methods for handling date and time operations.

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.



Methods

constructor

Time constructor.

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

Parameters:

ParameterTypeDescription
$datetimestring|nullOptional datetime string.
$timezone\DateTimeZone|string|nullOptional timezone.

Throws:


timezone

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

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

Parameters:

ParameterTypeDescription
$timezone\DateTimeZone|stringOptional timezone to associate with the current DateTime instance.

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:

ParameterTypeDescription
$timezone\DateTimeZone|string|nullOptional timezone.

Return Value:

self - New DateTimeImmutable object.

Throws:


parse

Returns a new Time instance while parsing a datetime string.

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

Parameters:

ParameterTypeDescription
$datetimestringDatetime string to parse.
$timezone\DateTimeZone|string|nullOptional timezone.

Return Value:

self - New DateTimeImmutable object.

Throws:


today

Return a new time with the time set to midnight.

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

Parameters:

ParameterTypeDescription
$timezone\DateTimeZone|string|nullOptional timezone.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


yesterday

Returns an instance set to midnight yesterday morning.

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

Parameters:

ParameterTypeDescription
$timezone\DateTimeZone|string|null

Return Value:

self - Return new DateTimeImmutable object.

Throws:


setTimezone

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

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

Parameters:

ParameterTypeDescription
$timezone\DateTimeZone|stringTimezone to set.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


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:

ParameterTypeDescription
$timezonenull|\DateTimeZone|stringOptional timezone string.

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.


getInstanceUtc

Returns Datetime instance of UTC timezone.

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

Parameters:

ParameterTypeDescription
$datetime\DateTimeInterface|\Luminova\Time\Time|stringDatetime object or string
$timezone\DateTimeZone|string|nullOptional timezone.

Return Value:

\DateTime - Return new datetime instance of UTC timezone.

Throws:


toFormat

Returns a formatted datetime to your preferred format.

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

Parameters:

ParameterTypeDescription
$formatnull|stringFormat to return (default: yyyy-MM-dd HH:mm:ss).

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:


fromInstance

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

public static fromInstance(\DateTimeInterface $datetime): self

Parameters:

ParameterTypeDescription
$datetime\DateTimeInterfaceAn instance of DateTimeInterface.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


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:

ParameterTypeDescription
$timestampintTimestamp to create datetime from.
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


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:

ParameterTypeDescription
$yearint|nullYear to pass.
$monthint|nullMonth to pass.
$dayint|nullDay to pass.
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


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:

ParameterTypeDescription
$hourint|nullHour to pass.
$minutesint|nullMinutes to pass.
$secondsint|nullSeconds to pass.
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


fromRelative

Returns a new datetime instance from a relative time format.

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

Parameters:

ParameterTypeDescription
$datetimestringRerative time string (2 days ago, -3 years etc..).
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

string - Return formatted DateTime string.

Throws:


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:

ParameterTypeDescription
$yearint|nullYear to pass.
$monthint|nullMonth to pass.
$dayint|nullDay to pass.
$hourint|nullHour to pass.
$minutesint|nullMinutes to pass.
$secondsint|nullSeconds to pass.
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


tomorrow

Returns an instance set to midnight tomorrow morning.

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

Parameters:

ParameterTypeDescription
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

self - Return new DateTimeImmutable object.

Throws:


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:

ParameterTypeDescription
$formatstringFormat to convert to
$datetimestringdatetime to convert to format.
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

\DateTimeImmutable|false - Returns new DateTimeImmutable false otherwise

Throws:


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:

ParameterTypeDescription
$month?stringMonth default is date('n).
$year?stringYear default is date('y').
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

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:

ParameterTypeDescription
$monthstring|int|nullThe month (1-12).
$yearstring|int|nullThe year (e.g., 2023).
$formatstringThe format for the returned dates (default is 'd-M-Y').

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:

ParameterTypeDescription
$formatstringThe format for the returned dates (default is "M").

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:

ParameterTypeDescription
$startint|string|nullStarting year. Defaults to the current year if not provided.
$endint|string|nullEnding year. Defaults to the current year minus 3 years if not provided.

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:

ParameterTypeDescription
$intervalintThe interval in minutes. Default is 30.

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:

ParameterTypeDescription
$datetimestring|int|\Luminova\Time\Time|\DateTimeImmutableThe datetime string, Unix timestamp, or time string.
$fullboolReturn full relative time (e.g. 1 hour, 3 minutes, 5 seconds ago) default is false.
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

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:

ParameterTypeDescription
$agostringSocial time ago.
$timezone\DateTimeZone|string|nullOptional timezone to associate with current DateTime instance.

Return Value:

\DateTime - Return new datetime instance.

Throws:


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:

ParameterTypeDescription
$datetimestring|int|\Luminova\Time\Time|\DateTimeImmutableEither a Unix timestamp, DateTimeImmutable or a string representing a date/time.
$minutesintThe number of minutes to check against.
$timezone\DateTimeZone|string|nullOptional timezone.

Return Value:

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

Throws:


suffix

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

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

Parameters:

ParameterTypeDescription
$daystring|intThe day for which to determine the suffix.

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:

ParameterTypeDescription
$datetimestringThe datetime string to check.

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:

ParameterTypeDescription
$datetimestringThe datetime string to check.

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:

ParameterTypeDescription
$datetimestringThe datetime string to check.

Return Value:

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