/ 
Developer-Dashboard-4.45
/ Developer::Dashboard::TimeUtils

NAME

Developer::Dashboard::TimeUtils - shared ISO-8601 timestamp helper

SYNOPSIS

use Developer::Dashboard::TimeUtils qw(_now_iso8601);
my $utc_stamp   = _now_iso8601( tz => 'utc' );    # '2026-09-15T16:14:00Z'
my $local_stamp = _now_iso8601( tz => 'local' );  # '2026-09-15T17:14:00+0100'

DESCRIPTION

Provides _now_iso8601, the single home for a timestamp helper that used to be written out seven separate times across Developer::Dashboard::ActionRunner, SessionStore, Housekeeper, RuntimeManager, Auth, Collector, and CollectorRunner (DD-894) - the same "small helper reimplemented per file instead of shared" pattern this project already fixed in Developer::Dashboard::DirEntries (DD-762) and Developer::Dashboard::TextUtils (DD-891).

PURPOSE

Give every module that needs the current timestamp in ISO-8601 form one canonical implementation to call, in either of the two formats this project intentionally uses, rather than each maintaining its own private copy of one or the other that can silently drift.

WHY IT EXISTS

Five modules (ActionRunner, SessionStore, Housekeeper, RuntimeManager, Auth) needed a UTC/Z-suffixed timestamp; two (Collector, CollectorRunner) needed the machine's local time with a numeric offset, so that collector-status timestamps and log headers line up with cron scheduling on the same machine across daylight-saving transitions (documented in Developer::Dashboard's own POD). The two formats are a deliberate, permanent split - not a bug (an earlier card, DD-642, wrongly claimed it was a bug and was correctly discarded) - so this extraction takes an explicit tz parameter rather than merging the two into one format.

WHEN TO USE

Any module in this codebase that needs the current timestamp in ISO-8601 form should use this module rather than writing a private _now_iso8601, choosing tz = 'utc'> or tz = 'local'> to match whichever of the two formats its own output already needs.

HOW TO USE

use Developer::Dashboard::TimeUtils qw(_now_iso8601);
my $stamp = _now_iso8601( tz => 'utc' );      # gmtime, 'Z' suffix
my $stamp = _now_iso8601( tz => 'local' );    # localtime, numeric offset

Calling without tz, or with any value other than 'utc'/'local', dies naming tz rather than silently defaulting - a caller must state which format it needs.

WHAT USES IT

Developer::Dashboard::ActionRunner, SessionStore, Housekeeper, RuntimeManager, and Auth (all tz = 'utc'>); Collector and CollectorRunner (both tz = 'local'>) - the 7 call sites the DD-894 extraction migrated.

EXAMPLES

_now_iso8601( tz => 'utc' )     # '2026-09-15T16:14:00Z'
_now_iso8601( tz => 'local' )   # '2026-09-15T17:14:00+0100'