SlotFlow API Documentation

TimeAxis
in package

FinalYes

Canonical discrete time axis used by timed slot-space expansion.

Time keys are normalized to a canonical shorthand such as h12. The shorthand is derived from the first letter of the bucket name and any configured aliases, such as day or shift.

Table of Contents

Properties

$aliases  : array<non-empty-string, int>
$allMultipliers  : array<non-empty-string, int>
$bucket  : non-empty-string
$bucketShorthand  : non-empty-string
$horizon  : int
$humanKeyParts  : array<int, non-empty-string>
$secondsInBucket  : int
$shorthandMultipliers  : array<non-empty-string, int>
$timeZero  : DateTimeImmutable

Methods

__construct()  : mixed
Create one discrete time axis and validate its bucket and alias shorthand scheme.
ceil()  : int
Return the first bucket index at or after the given value.
contains()  : bool
Return true when the given time expression resolves within the configured horizon.
dateTime()  : DateTimeImmutable
Return the bucket-aligned datetime for one resolved bucket index or accepted input.
define()  : self
Build one time axis from a canonical bucket name, horizon, and optional aliases.
humanKey()  : string
Return one human-readable time key, preferring larger configured units first.
key()  : string
Return the canonical serialized time key for one bucket index.
normalize()  : string
Normalize any accepted time expression to canonical `bucket shorthand + index`.
parse()  : int
Parse a time key or duration expression into canonical bucket count.
startingNow()  : self
Build one time axis anchored to the current wall-clock instant.
defaultSecondsInBucket()  : int
normalizeHumanKeyParts()  : array<int, non-empty-string>
normalizeTimeZero()  : DateTimeImmutable
Normalize the given time zero to align with the bucket boundaries.
resolveTimeZero()  : DateTimeImmutable

Properties

$aliases read-only

public array<non-empty-string, int> $aliases

$allMultipliers read-only

public array<non-empty-string, int> $allMultipliers

$bucket read-only

public non-empty-string $bucket

$bucketShorthand read-only

public non-empty-string $bucketShorthand

$humanKeyParts read-only

public array<int, non-empty-string> $humanKeyParts

$secondsInBucket read-only

public int $secondsInBucket

$shorthandMultipliers read-only

public array<non-empty-string, int> $shorthandMultipliers

$timeZero read-only

public DateTimeImmutable $timeZero

Methods

__construct()

Create one discrete time axis and validate its bucket and alias shorthand scheme.

public __construct(string $bucket, int $secondsInBucket, DateTimeImmutable|string $timeZero, int $horizon[, array<non-empty-string, int> $aliases = [] ][, array<int, non-empty-string>|null $humanKeyParts = null ]) : mixed
Parameters
$bucket : string

canonical name of the base time unit, such as "hour". First letter is used as the default shorthand, such as "h".

$secondsInBucket : int

size of one bucket in seconds

$timeZero : DateTimeImmutable|string

anchor instant for bucket index 0; strings are parsed via DateTimeImmutable and normalized down to the nearest bucket boundary

$horizon : int

maximum time index allowed on this axis (inclusive)

$aliases : array<non-empty-string, int> = []

map of human-friendly alias => bucket multiplier. Value may be suffixed with a shorthand letter, such as day: d to specify the alias shorthand explicitly (otherwise derived from first letter of alias).

$humanKeyParts : array<int, non-empty-string>|null = null

ordered human-key shorthands such as ['d', 'h']

ceil()

Return the first bucket index at or after the given value.

public ceil(int|string|DateTimeImmutable $value) : int
Parameters
$value : int|string|DateTimeImmutable
Return values
int

contains()

Return true when the given time expression resolves within the configured horizon.

public contains(int|string|DateTimeImmutable $value) : bool
Parameters
$value : int|string|DateTimeImmutable
Return values
bool

dateTime()

Return the bucket-aligned datetime for one resolved bucket index or accepted input.

public dateTime(int|string|DateTimeImmutable $value) : DateTimeImmutable
Parameters
$value : int|string|DateTimeImmutable
Return values
DateTimeImmutable

define()

Build one time axis from a canonical bucket name, horizon, and optional aliases.

public static define(string $bucket, int $horizon[, array<non-empty-string, int> $aliases = [] ][, array<int, non-empty-string>|null $humanKeyParts = null ][, DateTimeImmutable|string|null $timeZero = null ][, int|null $secondsInBucket = null ]) : self
Parameters
$bucket : string
$horizon : int
$aliases : array<non-empty-string, int> = []
$humanKeyParts : array<int, non-empty-string>|null = null
$timeZero : DateTimeImmutable|string|null = null
$secondsInBucket : int|null = null
Return values
self

humanKey()

Return one human-readable time key, preferring larger configured units first.

public humanKey(int|string|DateTimeImmutable $value) : string
Parameters
$value : int|string|DateTimeImmutable
Return values
string

key()

Return the canonical serialized time key for one bucket index.

public key(int $index) : string
Parameters
$index : int
Return values
string

normalize()

Normalize any accepted time expression to canonical `bucket shorthand + index`.

public normalize(int|string|DateTimeImmutable $value) : string
Parameters
$value : int|string|DateTimeImmutable
Return values
string

parse()

Parse a time key or duration expression into canonical bucket count.

public parse(int|string|DateTimeImmutable $value) : int

Examples: h12, 3d, d3s1, 3ds1, 12.

Parameters
$value : int|string|DateTimeImmutable
Return values
int

startingNow()

Build one time axis anchored to the current wall-clock instant.

public static startingNow(string $bucket, int $horizon[, array<non-empty-string, int> $aliases = [] ][, array<int, non-empty-string>|null $humanKeyParts = null ][, DateTimeImmutable|string|null $now = null ][, int|null $secondsInBucket = null ]) : self

The provided instant is normalized down to the nearest bucket boundary so bucket index 0 always starts on a canonical bucket edge.

Parameters
$bucket : string
$horizon : int
$aliases : array<non-empty-string, int> = []
$humanKeyParts : array<int, non-empty-string>|null = null
$now : DateTimeImmutable|string|null = null
$secondsInBucket : int|null = null
Return values
self

defaultSecondsInBucket()

private static defaultSecondsInBucket(string $bucket) : int
Parameters
$bucket : string
Return values
int

normalizeHumanKeyParts()

private normalizeHumanKeyParts(array<int, non-empty-string>|null $humanKeyParts) : array<int, non-empty-string>
Parameters
$humanKeyParts : array<int, non-empty-string>|null
Return values
array<int, non-empty-string>

normalizeTimeZero()

Normalize the given time zero to align with the bucket boundaries.

private normalizeTimeZero(DateTimeImmutable $timeZero) : DateTimeImmutable

This ensures that the time zero is always a multiple of the bucket size.

Parameters
$timeZero : DateTimeImmutable
Return values
DateTimeImmutable

resolveTimeZero()

private resolveTimeZero(DateTimeImmutable|string $timeZero) : DateTimeImmutable
Parameters
$timeZero : DateTimeImmutable|string
Return values
DateTimeImmutable 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results