laranail/chrono

laranail/chrono is not published to Packagist, so there is no registry-version badge to show: see Install.

Timezones, formatting and humanised time for Laravel — a tzdata-parity IANA catalogue with a fluent query builder, a resolver that turns messy input into a canonical identifier, and daylight-saving conversion with explicit policies for the two wall-clock readings a year that name no instant, or two.

Built on a framework-free core that never calls date_default_timezone_set() and never rewrites app.timezone, so your storage stays UTC and zones remain an input and presentation concern. Every "now" comes from an injected PSR-20 clock, which is what makes daylight-saving behaviour testable. Requires PHP ^8.5 with ext-intl and ext-calendar, on Laravel ^13.

Install

composer require laranail/chrono

Quick start guide and usage

Getting started

Nothing is required: the service provider and the Chrono and Timezones facades are auto-discovered, and every config key has a working default. Optionally:

1. Publish the config (writes config/laranail/chrono.php): php artisan vendor:publish --tag=laranail::chrono-config.
2. Publish the translations to override validation messages: php artisan vendor:publish --tag=laranail::chrono-translations.
3. Check the tzdata release PHP is carrying with Timezones::version(); two or more years old means the host is wrong about any country that has changed its rules since.

Usage

use Simtabi\Laranail\Chrono\Facades\Timezones;

Timezones::of('Asia/Calcutta');          // Asia/Kolkata — the deprecated alias is canonicalised
Timezones::of('Pacific Standard Time');  // America/Los_Angeles — a Windows id from an Outlook invite
Timezones::of('KE');                     // Africa/Nairobi

Timezones::query()
    ->inRegion(Region::Africa)
    ->observingDst(false)
    ->orderByOffset()
    ->toSelectOptions();                 // grouped, offset-labelled, ready for a <select>

$newYork = Timezones::of('America/New_York');

$newYork->at('2026-03-08 02:30');                        // 03:30 EDT — that reading never existed
$newYork->at('2026-03-08 02:30', GapPolicy::Throw);      // SkippedLocalTime
$newYork->inspect('2026-11-01 01:30')->isAmbiguous();    // true — it happened twice

Why

PHP resolves both pathological wall-clock readings silently, and its choice for the ambiguous one is not consistent between zones: Europe/London 2025-10-26 01:30 yields the later instant while America/New_York 2025-11-02 01:30 yields the earlier, from the same build. A booking stored in two cities gets opposite disambiguation and nothing says so. This package makes that choice explicit, and keeps it the same everywhere.

Documentation

Hosted at opensource.simtabi.com/documentation/laranail/chrono.

Guides

• Installation — requirements, install, what to publish
• Getting started — the mental model and the first calls
• Configuration — every key and its environment variable
• Daylight saving — gaps, ambiguity, and the zones that break assumptions
• The catalogue — canonical, deprecated, fixed and legacy identifiers
• Architecture — the layering, the clock, and what ships when
• Release — cutting a version, keeping generated data current

Reference

• Facades and helpers — Chrono, Timezones, and injecting instead
• Traits — one use line, with a container or without one
• Resolution — the nine-strategy chain, and when it refuses
• Querying — the fluent builder, collections and select shapes
• Converting between zones — one instant or many, one zone or many
• Presentation — optgroups, labels, field sets and output shapes
• Temporal value types — dates, times, durations PHP lacks
• Periods — spans that compare, overlap, subtract and draw
• The Timezone object — offsets, transitions, wall-clock readings
• Formatting and parsing — named formats, ICU skeletons, the parsing traps
• Humanised time — relative phrasing with correct plural rules
• The picker component — progressive enhancement, search, a11y
• Commands — show, list, doctor, sync
• Casts and validation — storing a zone, and refusing bad input
• Enums — three generated, nine authored
• Generated data — the alias map and the sync check

Recipes

• Build a timezone picker
• Store a user's timezone
• Resolve messy input
• Handle a DST gap or ambiguity
• Test with a frozen clock
• Migrate from pheg's time toolbox
• Migrate off the package-tools enum

Stability

Pre-1.0, with immutable tags — every release is its own v0.1.x and none is ever re-pointed, so a lockfile means something. Constraints resolve ^0.1. Calendars, recurrence, intervals and business days are planned for v0.2 and v0.3; see the roadmap.

Contributing & security

Issues and PRs are welcome — see CONTRIBUTING.md; make lists every task. Report vulnerabilities per SECURITY.md (opensource@simtabi.com); participation follows the Code of Conduct.

License

MIT © Simtabi LLC. See LICENSE.