Logo

Accepted Input Types

Tokei methods accept multiple representations of the same temporal concept. Values are automatically converted when possible.

Time values

A time can be expressed using any of the following types:

  • Time
  • Event
  • DateTimeInterface

Example:

use Bakame\Tokei\Interval;

Interval::between(Time::noon(), Time::endOfDay());
Interval::between(new DateTime('2026-05-23 15:23:16'), Time::endOfDay());
Interval::between(Event::at(Time::noon(), 'lunch'), new DateTime('2026-05-23 15:23:16'));

The date and timezone components of the DateTimeInterface object are ignored when used as a Time instance parameter.

$interval = Interval::between(
    Event::at(Time::noon(), 'lunch'),
    new DateTime('2026-05-23 15:23:16', new DateTimeZone('Europe/Brussels'))
);
$interval->end->format(TimeFormat::Clock);
// returns '15:23:16'

Duration values

A duration can be expressed using any of the following types:

  • Duration
  • Interval
  • Task
  • DateInterval
  • Time\Duration

Example:

Interval::since(
    new DateTime('2026-05-23 15:23:16'), 
    new DateInterval('PT3H')
);

Interval::since(
    new DateTime('2026-05-23 15:23:16'), 
    \Time\Duration::fromHours(3),
);
  • For Interval types, the interval duration property will be used.

DateInterval instances which do not use deterministic component will be rejected and throw an InvalidDuration exception if provided in place of a Duration instance.

Interval::since(
    new DateTime('2026-05-23 15:23:16'), 
    new DateInterval('P1MT3H')
);
//will throw because the month component is used

When a DateInterval instance is generated through DateTimeInterface::diff, intervals containing months or years are still accepted because the DateInterval::days property contains the resolved duration in days.

Interval values

An interval can be expressed using any of the following types:

  • Interval
  • Task

All remarks related to DateTimeInterface and DateInterval usages are applicable for interval types.

Identifier values

Identifiers can be expressed using:

  • Identifiers
  • classes implementing the HasIdentifiers interface
  • string
  • iterable<Identifiers|HasIdentifiers|string>

Timezone

Timezone can be expressed using:

  • DateTimeZone object
  • DateTimeInterface object, its getTimezone method will be called
  • non-empty-string representing a timezone identifier

Input rules

Concept Accepted representations
Time Time, Event, DateTimeInterface
Duration Duration, DateInterval, Interval, Task, Time\Duration
Interval Interval, Task
Identifiers Identifiers, HasIdentifiers, string, iterable
Timezone DateTimeZone, DateTimeInterface, string,

Unless stated otherwise, parameters documented as Time, Duration, or Interval accept any of the compatible representations listed above. For brevity, the API documentation uses the temporal primitive as the parameter type rather than repeating the complete union type.

Time representations

Tokei Time-based types represent time-of-day semantics only.
Date and timezone information are not part of their model.

  • Time
  • Event
  • Interval
  • Task

When a DateTimeInterface is used in a Time-based context, only the time-of-day is used.

Logo