Nova Worldclock Card Laravel Package

Getting Started

Prerequisites. Laravel Nova (the card is worthless outside Nova) and PHP ≥ 8.4 if you install ^3.4. If you are still on 8.3, composer require fails at resolution — pin ^3.3.1 and treat the PHP upgrade as a separate change set so the failure is attributable to the runtime, not the card.

Install and register. Three commands and one edit:

composer require interaction-design-foundation/nova-worldclock-card
php artisan vendor:publish --tag=nova-worldclock-card   # confirm the tag from the interactive list

Then register the card wherever Nova cards are declared. The card class lives under InteractionDesignFoundation\NovaWorldclockCard\... — ls vendor/interaction-design-foundation/nova-worldclock-card/src gives you the exact name before you type it:

// app/Providers/NovaServiceProvider.php
public function cards(): array
{
    return [
        // ...existing cards
        \InteractionDesignFoundation\NovaWorldclockCard\WorldclockCard::make(),
    ];
}

First use case. Open config/nova-worldclock-card.php (or whatever the published file is named) and replace the placeholder zones with your real ones. The single highest-value configuration for a distributed team is the on-call region plus each office:

return [
    'timezones' => [
        'Europe/Lisbon'      => 'Lisbon — HQ',
        'America/New_York'   => 'New York — Support',
        'Asia/Kolkata'       => 'Bengaluru — On-call',
    ],
    'hour_format' => 24, // check the key name in the published file
];

Deploy, php artisan config:cache if you cache config in production, hard-refresh the dashboard. Look first at the rendered card, not the source — the package's entire surface is that widget, and a blank card is the only failure mode you will realistically hit.

Implementation Patterns

Scope the card to the dashboard that needs it. Registering in NovaServiceProvider::cards() puts the clock on the main dashboard for everyone. For anything narrower, declare it on a custom Dashboard class instead, so incident responders and finance don't share the same dashboard real estate:

// app/Nova/Dashboards/OpsDashboard.php
public function cards(): array
{
    return [
        WorldclockCard::make()->width('1/3'),
    ];
}

Use IANA identifiers, never abbreviations. America/New_York, not EST. Abbreviations are ambiguous (CST is three different zones), and they break the moment a region shifts DST. The card resolves offsets from the tz database, so the identifier is the whole contract.

Label by role, not just city. The card is a coordination device, so the useful label answers "who do I need to reach" rather than "where is this":

'America/Los_Angeles' => 'SF — Eng on-call',
'Europe/Berlin'       => 'Berlin — Release approval',

Order matters. The list renders in declaration order. Put the zones people check under pressure at the top; the top-left position is the one that gets read during an incident. Order the list in version control and let it be reviewed like code — it's a small but real piece of on-call documentation.

Split into multiple cards for regional groups. When the list passes ~6 zones it stops being scannable at a glance and becomes a table. Two cards — "Follow the sun" (Americas/EMEA/APAC coverage) and "On-call" — beat one long card, and each gets its own dashboard placement.

Drive config from the environment when topology differs. Staging and local rarely care about the Bengaluru clock. Read the zone map through a small config helper or env-gated array so non-production dashboards don't accumulate noise:

'timezones' => env('NOVA_WORLDCLOCK_ZONES')
    ? json_decode(env('NOVA_WORLDCLOCK_ZONES'), true)
    : ['Europe/Lisbon' => 'Lisbon — HQ'],

Treat the card as a read-only shared reference, not a feature. The pattern that actually works: put it on the Ops dashboard next to the incident and deployment tools, so "what time is it for the reviewer" is answered without a context switch. Do not wire it into anything — it is a display widget with no outputs, no events, and no storage. Any conversion, availability search, overlap finding, or timezone-aware notification logic belongs in application code via Carbon; the presence of this card must not be read as a scheduling capability.

Gotchas and Tips

The PHP floor is the only breaking surface. 3.4.0 raised the minimum from 8.3 to 8.4. There is no API change, no config format change. If resolution fails, it's the runtime — check composer why-not interaction-design-foundation/nova-worldclock-card ^3.4 before debugging anything else.

Config changes are invisible until the cache is cleared. In production with config:cache, editing the zone list and deploying without php artisan config:cache (or a deploy hook that runs it) leaves the old clocks on screen indefinitely. This is the most common "the package is broken" report and it never is.

A blank card throws no error. Nova asset loading or card mounting can regress after a Nova upgrade and produce an empty card with a clean console-free page. Debug in this order: browser console for a 404 on card.js → php artisan nova:publish → is the compiled asset actually present in vendor/.../dist/js/ → php artisan view:clear && php artisan config:clear. Do not go spelunking in your own code first; the failure is almost always asset delivery.

Invalid timezone identifiers fail quietly or loudly, inconsistently. A typo like Europe/Lisbon (trailing space) or US/Eastern (a legacy alias that may or may not be in the tz data your build ships) can produce a missing row or a raw InvalidTimeZoneException depending on where the resolution happens. Validate the map in a test:

it('has valid worldclock zones', function () {
    foreach (config('nova-worldclock-card.timezones') as $tz => $label) {
        expect(in_array($tz, timezone_identifiers_list(), true))->toBeTrue("Bad tz: {$tz}");
    }
});

12/24-hour is global, not per-zone. If one office insists on 12-hour and another on 24-hour, the card cannot express that. Fork or accept the compromise — it is not a configurable-per-entry feature.

Time rendering is client-side. The clock reads the viewer's browser tz database, so a browser that hasn't been updated in months may disagree with your server for recently-changed DST rules (rare, but a real source of "the card says the wrong time" reports right after a government changes its offset). Cross-check against php artisan tinker → now()->setTimezone('...') before filing a bug.

Only touch the build toolchain if you compile from source. 3.4.0 pins webpack to fix a genuine laravel-mix 6.0.49 / webpack 5.107.0 breakage (lib/SizeFormatHelpers removed) and bumps webpack past CVE-2025-68157. If you consume the published artifact, none of this is yours — exclude it from review. If you fork and compile, note the CVE is not reachable here (experiments.buildHttp is unused); log it triaged and move on. Also check light/dark theme rendering manually after any Nova upgrade — there is no automated coverage for it.

The extension points are the config file and nothing else. There is no event, no slot, no render hook. If you want clickable zones, a "copy time" affordance, or per-user zones, you are forking or writing your own card, and at that point the build-vs-buy calculus from a 3-file Vue component changes. Keep the requirement to "a list of clocks" and this package stays cheap.

If the card isn't rendered on any dashboard, remove it. composer remove interaction-design-foundation/nova-worldclock-card deletes the PHP 8.4 constraint at zero feature cost. Run the usage audit before scheduling an upgrade — removal is frequently the cheaper and cleaner outcome.