Logo
Tokei

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
  • NativeEvent

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();
// returns '15:23:16'

Duration values

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

  • Duration
  • DateInterval
  • Interval
  • Task
  • NativeInterval
  • NativeTask

Example:

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

Interval::since(
    new DateTime('2026-05-23 15:23:16'), 
    Duration::of(hours: 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
  • NativeInterval
  • NativeTask

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>

Argument rules

Concept Accepted representations
Time Time, Event, DateTimeInterface, NativeEvent
Duration Duration, DateInterval, Interval, Task, NativeInterval, NativeTask
Interval Interval, Task, NativeInterval, NativeTask
Identifiers Identifiers, HasIdentifiers, string, iterable

Unless stated otherwise, any method accepting a temporal primitive also accepts any compatible representation of that primitive.

Time vs Native representations

Tokei distinguishes between two temporal domains:

Time-based types (no date/timezone)

  • Time
  • Event
  • Interval
  • Task

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

Native types (absolute datetime)

  • NativeEvent
  • NativeInterval
  • NativeTask
  • DateTimeInterface

These types represent real-world instants and preserve date and timezone information.

Conversion rule

When a DateTimeInterface is used in a Time-based context, only the time-of-day is used. When used in a Native context, the full datetime (date + timezone) is preserved.

Logo