Nova Worldclock Card Laravel Package

Getting Started

1. Confirm fit before installing. This is a Nova-only card (Laravel Nova 4/5 assumed — verify the exact laravel/nova constraint in composer.json). It will not work in plain Laravel, Filament, or Nova 3 without checking the nova requirement.

New in 3.4.0 — check your PHP version first. The minimum supported PHP is now 8.4 (was 8.3). This is a breaking change for consumers, not just a dev-environment bump:

php -v                      # must be >= 8.4
composer why-not idf/nova-worldclock-card 3.4.0

If you are still on PHP 8.3, stay on the 3.3.x line and pin it explicitly ("idf/nova-worldclock-card": "~3.3.0") so a routine composer update doesn't take you across the break. Also check any "platform": {"php": "8.3"} block in your root composer.json, Docker base images, CI matrix, and Herd/Valet — a platform override will silently keep you on the old line and produce a confusing "no version found" resolution error rather than a clear message.

2. Install via Composer.

composer require idf/nova-worldclock-card:^3.4

Because the package has a small star count and zero dependents, treat the install as a code review: open vendor/idf/nova-worldclock-card/ and read composer.json, src/, and resources/js/ before shipping it to production.

3. Where to look first (in this order):

4. Register the card. The typical Nova pattern is either in a dashboard or globally:

// app/Nova/Dashboards/Main.php
public function cards(): array
{
    return [
        (new \Idf\NovaWorldclockCard\WorldclockCard())
            ->width('1/2'),
    ];
}

or for every dashboard:

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

If the class name differs, composer dump-autoload -o then grep -r "class .*Card" vendor/idf/nova-worldclock-card/src gets you there in one command.

5. Publish config/assets if the README instructs it.

php artisan vendor:publish --provider="Idf\NovaWorldclockCard\CardServiceProvider"

First use case: drop one card on the main dashboard showing your distributed team's local times (e.g. Europe/Copenhagen, America/New_York, Asia/Kolkata) so on-call handoffs and standup scheduling don't require a separate world-clock tab.

Implementation Patterns

Config-driven timezone lists (preferred). If the package ships a config file, keep the list in config/nova-worldclock-card.php and read it from .env-driven app config so staging and prod don't diverge:

// config/nova-worldclock-card.php
'timezones' => [
    'Europe/Copenhagen' => 'HQ',
    'America/New_York'  => 'US East',
    'Asia/Kolkata'      => 'Support',
],

Commit the published config — Nova cards that cache config at boot will not pick up changes until php artisan config:clear.

Per-dashboard composition. Cards are cheap; instantiate the card multiple times with different slices of the world if you want, e.g. one "Team" card on Main, one "Support rotation" card on an operations dashboard. Prefer this over one card with fifteen cities — a Nova card is narrow and the value collapses once it scrolls.

Conditional visibility. Wrap registration in ->canSee(...) so the card only appears for people who need it (e.g. only users whose timezone column is outside the default region):

(new WorldclockCard())
    ->canSee(fn ($request) => $request->user()->hasAnyRole(['ops', 'support']))
    ->onlyOnDashboards(['main']);

Align with Laravel's timezone source of truth. Don't hardcode a separate list of offsets. Pass IANA names and let the card render; store each user's zone in users.timezone and use Nova::userTimezone() if you build a custom subclass that shows "you vs. them".

Custom subclass when defaults don't fit. If the constructor only accepts an array, extend it rather than editing vendor files:

namespace App\Nova\Cards;

class TeamWorldclock extends \Idf\NovaWorldclockCard\WorldclockCard
{
    public $width = '1/2';

    public function __construct()
    {
        parent::__construct([
            'Europe/Copenhagen' => 'HQ',
            'America/New_York'  => 'NYC',
        ]);
    }
}

This is the extension point that survives a composer update.

Pair with an ops workflow. The card is read-only display. If you need the times to do something (page an on-call, show next standup countdown), compute that in a custom Nova metric or a separate card — don't try to bend this one into business logic.

Gotchas and Tips

Timezone identifiers must be IANA names, not abbreviations. CET, EST, IST are ambiguous (IST is India and Ireland) and will either throw in Intl.DateTimeFormat or silently render the wrong hour. Always Europe/Copenhagen, America/New_York, Asia/Kolkata. Validate against timezone_identifiers_list() in a test if the list is user-editable.

DST is the whole reason to use this package. A card showing fixed UTC offsets is actively harmful — half the year your "9am standup" card is an hour off for one participant. If you find yourself passing +02:00, stop and pass the zone name.

3.4.0 fixes the asset build — read it as an upgrade instruction, not trivia. Previously laravel-mix floated webpack: ^5.60.0, which resolved to webpack 5.107.0 and broke on the removed lib/SizeFormatHelpers, while 5.102+ also tightened ProgressPlugin option validation. 3.4.0 pins webpack at 5.104.1. Practical consequences:

• If you have been carrying a local overrides/resolutions block, a vendored webpack pin, or a patched webpack.mix.js inside vendor/ to get the card to build, remove it before upgrading — it will conflict with the package's own pin and you'll get a duplicate-webpack or option-validation error.
• If your application's build also processes the card's JS (some teams import the Vue component directly into an app bundle), your root webpack version matters too. Stay below 5.107 until your own config no longer relies on lib/SizeFormatHelpers.
• Rebuild after upgrading rather than trusting a stale dist/ — Nova serves whatever is committed in the package, and a mixed old/new dist is the classic blank-card cause.

# if you must build from vendor (not recommended, wiped on composer update)
cd vendor/idf/nova-worldclock-card && npm ci && npm run prod

Use npm ci (not npm install) so you honor the committed lockfile and the new webpack pin.

Blank white card — the most common install failure. Nova cards ship a built dist/js/card.js. If the card renders as a blank box: check the browser console for a failed asset request, verify resources/js/card.js registers the same component name the PHP class returns from component(), and confirm the package's dist/ is actually committed. Also confirm your Nova asset manifest is fresh.

Card width defaults are usually wrong. Nova cards default to one-third width; a multi-city clock gets cramped. Set ->width('1/2') or 'full' explicitly.

Publish-then-forget bite. If you published the config, a package update that adds new keys will not merge them into your copy. Check the package's config diff on every composer update, or delete your published copy and rely on mergeConfigFrom defaults.

Nova authorization runs first. A card that throws inside its calculate/jsonSerialize (e.g. invalid timezone string) can take down the whole dashboard. Sanitize the timezone input and fail soft — wrap the parse in a try/catch and render a placeholder rather than a 500.

Debugging checklist:

1. php artisan nova:publish then hard-refresh (Nova caches its own asset manifest)
2. php artisan config:clear && php artisan view:clear
3. Browser console → Vue warnings naming the unregistered component
4. php artisan route:list | grep nova to confirm the card's route/asset is served
5. php -v and composer show idf/nova-worldclock-card — on 3.4.0 a surprising number of "broken card" reports will actually be a half-completed PHP 8.4 upgrade

Version pinning. With zero dependents and a tiny star count, a minor-version regression is plausible and nobody upstream will catch it. Pin in composer.json ("idf/nova-worldclock-card": "^3.4" with a locked composer.lock) and keep a five-line fallback: a Nova::script-free custom Vue card or even a Markdown/HTML card rendering now()->setTimezone($tz) server-side. The clock is genuinely 20 lines of code — the value here is convenience, not unique capability.

Security posture. 3.4.0 bumps webpack to 5.104.1 covering CVE-2025-68157 (HttpUriPlugin allowedUris bypass via redirects). The maintainers note it's only reachable with experiments.buildHttp enabled, which this package does not use — so it's not a reason to rush the 8.4 upgrade on its own. But if you copy the package's webpack config into an app that does enable buildHttp, treat that bump as mandatory.

Don't assume Laravel 13 yet. The release notes describe "Laravel 13 support groundwork" and PHP 8.5 in CI — groundwork, not a compatibility guarantee. Verify the illuminate/* constraints in composer.json against your actual Laravel version before planning an upgrade, and don't let "supports Laravel 13" leak into internal docs.

Don't adopt the package's tooling. 3.4.0 chains PHP-CS-Fixer before phpcbf under composer cs. That lints the package, not your application. Never wire the package's script into your CI or run composer cs from the package directory expecting it to touch your code.

Fork readiness. Given the maintenance profile, plan for the case where you need to patch it: keep customizations inside App\Nova\Cards\* subclasses, never in vendor/, and if you must fork, use a Composer VCS repository entry so the swap is a one-line composer.json change. A fork is also the cheapest escape hatch if you're stuck on PHP 8.3 and need a fix that only landed in 3.4.x — cherry-pick the webpack pin onto 3.3.1 rather than upgrading PHP app-wide for a dashboard clock.