Oihana PHP

date

Table of Contents

Classes

DurationUnit
Defines the canonical single-letter suffixes of a duration unit.

Functions

addDays()  : DateTimeImmutable
Returns a copy of a date shifted by a number of days.
durationToSeconds()  : float
Normalizes a duration expressed in any supported form into a number of seconds.
formatDateTime()  : string
Formats a given date/time string into a specified format and timezone.
humanizeDuration()  : string
Returns a human-readable representation of a duration, e.g. `"1d 2h 3m 4s"`.
isDate()  : bool
Indicates if the passed-in expression is a valid date with a specific format (default 'Y-m-d').
isFuture()  : bool
Tells whether a date is strictly in the future.
isPast()  : bool
Tells whether a date is strictly in the past.
isValidTimezone()  : bool
Indicates if the passed-in expression is a valid timezone.
isWeekend()  : bool
Tells whether a date falls on a weekend (Saturday or Sunday).
now()  : string
Returns the current date/time as a formatted string.

Functions

addDays()

Returns a copy of a date shifted by a number of days.

addDays(DateTimeInterface $date, int $days) : DateTimeImmutable

A new DateTimeImmutable is returned ; the source date is never modified. A negative $days shifts the date backwards.

Parameters
$date : DateTimeInterface

The source date.

$days : int

The number of days to add (negative to subtract).

Tags
throws
DateMalformedStringException

Never thrown in practice (the modifier is always well-formed).

example 
use function oihana\core\date\addDays;

addDays( new DateTimeImmutable( '2026-01-01' ) , 5 )  ; // 2026-01-06
addDays( new DateTimeImmutable( '2026-01-01' ) , -1 ) ; // 2025-12-31
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
DateTimeImmutable —

A new immutable date shifted by $days days.

durationToSeconds()

Normalizes a duration expressed in any supported form into a number of seconds.

durationToSeconds([int|float|string|null $duration = null ][, int $hoursPerDay = 24 ]) : float

The $duration may be:

  • an int|float number of seconds (e.g. 3725), returned as-is (cast to float),
  • a colon string "MM:SS" or "HH:MM:SS",
  • a unit string "1.5d 3h 15m 12.5s" (any subset, any order, decimals allowed),
  • or null (treated as a zero duration → 0.0).

A day is worth $hoursPerDay hours, so the d unit of a unit string is converted accordingly (a colon string never carries a day component).

Parameters
$duration : int|float|string|null = null

The duration to convert.

$hoursPerDay : int = 24

Hours in a day for the d unit (default 24).

Tags
example 
use function oihana\core\date\durationToSeconds ;

durationToSeconds( 3725 ) ;        // 3725.0
durationToSeconds( '90:00' ) ;     // 5400.0
durationToSeconds( '1h 30m' ) ;    // 5400.0
durationToSeconds( '1.5d' , 8 ) ;  // 43200.0  (1.5 × 8h)
durationToSeconds( null ) ;        // 0.0
author

Marc Alcaraz (ekameleon)

since
1.2.0
Return values
float —

The total number of seconds (0.0 for an empty duration).

formatDateTime()

Formats a given date/time string into a specified format and timezone.

formatDateTime([string|null $date = null ][, string $timezone = 'UTC' ][, string|null $format = 'Y-m-d\TH:i:s.v\Z' ]) : string

This function attempts to validate and parse the input date string. If the input date is not valid according to the provided format, it defaults to the current date/time ("now"). It then applies the specified timezone and returns the formatted date string.

The $timezone parameter is used only to interpret the input date string. Regardless of the input timezone, the resulting string is always converted to UTC and formatted with a trailing "Z".

Parameters
$date : string|null = null

The input date/time string to format. If null or invalid, "now" is used.

$timezone : string = 'UTC'

The timezone identifier (e.g., 'Europe/Paris'). Defaults to 'UTC'.

$format : string|null = 'Y-m-d\TH:i:s.v\Z'

The date format string compatible with DateTime::format(). Defaults to 'Y-m-d\TH:i:s.v\Z' (ISO 8601 UTC with milliseconds).

Tags
throws
DateInvalidTimeZoneException

If the provided timezone string is invalid.

DateMalformedStringException

If the input date string is malformed or cannot be parsed.

example 
echo formatDateTime('2025-07-20 15:30', 'Europe/Paris', 'Y-m-d H:i');
// Output: '2025-07-20 15:30'

echo formatDateTime();
// Output: current date/time in UTC, e.g., '2025-07-20T13:30:20.676Z'
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

The formatted date/time string, or null if creation fails.

humanizeDuration()

Returns a human-readable representation of a duration, e.g. `"1d 2h 3m 4s"`.

humanizeDuration([int|float|string|null $duration = null ][, int $hoursPerDay = 24 ]) : string

The $duration may be:

  • an int|float number of seconds (e.g. 3725),
  • a colon string "MM:SS" or "HH:MM:SS",
  • a unit string "1.5d 3h 15m 12.5s" (any subset, any order),
  • or null (treated as a zero duration → "0s").

Whatever the input form, the duration is first normalized into a number of seconds and then broken down so that every component stays within its natural range (seconds < 60, minutes < 60, hours < $hoursPerDay). Fractional input therefore rolls up correctly: "90:00" and "1.5h" both yield "1h 30m". Only the seconds component may carry a fractional part (e.g. "5.5s").

Parameters
$duration : int|float|string|null = null

The duration to format.

$hoursPerDay : int = 24

Hours in a day for day↔hour conversion (default 24).

Tags
example 
use function oihana\core\date\humanizeDuration ;

echo humanizeDuration( 3725 ) ;        // "1h 2m 5s"
echo humanizeDuration( '1h 30m' ) ;    // "1h 30m"
echo humanizeDuration( '90:00' ) ;     // "1h 30m"
echo humanizeDuration( null ) ;        // "0s"
author

Marc Alcaraz (ekameleon)

since
1.2.0
Return values
string —

The human-readable duration (e.g. "1h 42m"), "0s" for an empty duration.

isDate()

Indicates if the passed-in expression is a valid date with a specific format (default 'Y-m-d').

isDate(string|null $date[, string $format = 'Y-m-d' ]) : bool
Parameters
$date : string|null

The expression to evaluate.

$format : string = 'Y-m-d'

The date format (default 'Y-m-d').

Tags
example 
var_dump(isDate('2025-07-20'));           // true
var_dump(isDate('20/07/2025', 'd/m/Y'));  // true
var_dump(isDate('invalid-date'));         // false
var_dump(isDate(null));                   // false
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

Indicates if the passed-in expression is a valid timezone.

isFuture()

Tells whether a date is strictly in the future.

isFuture(DateTimeInterface $date[, DateTimeInterface|null $now = null ]) : bool
Parameters
$date : DateTimeInterface

The date to test.

$now : DateTimeInterface|null = null

The reference "now". Defaults to the current date/time.

Tags
example 
use function oihana\core\date\isFuture;

isFuture( new DateTimeImmutable( '2999-01-01' ) ) ; // true
isFuture( new DateTimeImmutable( '2000-01-01' ) ) ; // false
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
bool —

true if $date is strictly after $now, false otherwise.

isPast()

Tells whether a date is strictly in the past.

isPast(DateTimeInterface $date[, DateTimeInterface|null $now = null ]) : bool
Parameters
$date : DateTimeInterface

The date to test.

$now : DateTimeInterface|null = null

The reference "now". Defaults to the current date/time.

Tags
example 
use function oihana\core\date\isPast;

isPast( new DateTimeImmutable( '2000-01-01' ) ) ; // true
isPast( new DateTimeImmutable( '2999-01-01' ) ) ; // false
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
bool —

true if $date is strictly before $now, false otherwise.

isValidTimezone()

Indicates if the passed-in expression is a valid timezone.

isValidTimezone([string|null $timezone = null ]) : bool

Note: timezone_identifiers_list() requires PHP >= 5.2

Parameters
$timezone : string|null = null

The timezone expression to evaluates.

Tags
example 
var_dump(isValidTimezone('Europe/Paris')); // true
var_dump(isValidTimezone('Invalid/Timezone')); // false
var_dum(isValidTimezone(null)); // false
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

Indicates if the passed-in expression is a valid timezone.

isWeekend()

Tells whether a date falls on a weekend (Saturday or Sunday).

isWeekend(DateTimeInterface $date) : bool
Parameters
$date : DateTimeInterface

The date to test.

Tags
example 
use function oihana\core\date\isWeekend;

isWeekend( new DateTimeImmutable( '2024-01-06' ) ) ; // true  (Saturday)
isWeekend( new DateTimeImmutable( '2024-01-08' ) ) ; // false (Monday)
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
bool —

true if the date is a Saturday or a Sunday, false otherwise.

now()

Returns the current date/time as a formatted string.

now([string $timezone = 'UTC' ][, string|null $format = 'Y-m-d\TH:i:s.v\Z' ]) : string

The $timezone parameter is used only to interpret the "now" value. Regardless of the input timezone, the resulting string is always converted to UTC and formatted with a trailing "Z".

Parameters
$timezone : string = 'UTC'

The timezone identifier (e.g., 'Europe/Paris'). Defaults to 'UTC'.

$format : string|null = 'Y-m-d\TH:i:s.v\Z'

The date format string compatible with DateTime::format(). Defaults to 'Y-m-d\TH:i:s.v\Z' (ISO 8601 UTC with milliseconds).

Tags
throws
DateInvalidTimeZoneException

If the provided timezone string is invalid.

DateMalformedStringException

If the date creation fails (should not occur with 'now').

example 
echo now() ;
// Output: '2025-07-20T15:30.676Z'

echo now('Europe/Paris');
// Output: '2025-07-20T13:30:20.676Z' (always UTC)
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

The formatted current date/time string.

On this page

Search results