Nova Clock Card Laravel Package

Getting Started

1. Install the package with Composer and let Laravel's package discovery register the service provider:

   composer require <vendor>/<package>
   

2. Publish the configuration (and any views/assets) so you can see the defaults before writing code:

   php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"
   

3. Open the published config file first — it is the quickest map of what the package can do (timezone, 12/24-hour format, display mode, asset paths). Check the README for the Blade component/namespace it registers.
4. First use case: drop an analogue clock into an existing dashboard or status view. In 1.2.0 the analogue display is a selectable rendering mode, so the smallest step is switching the display option (or passing the equivalent component attribute) from the digital default to analogue:

   <x-clock :time="now()" display="analogue" />
   

   If your app already renders a digital clock through this package, keep the existing call and change only the display option — that is the intended upgrade path for this release.

Implementation Patterns

• Config-first, then override per-instance. Set the analogue mode as the default in config/<package>.php for app-wide consistency, and pass a per-component override only where a view needs a different style. This keeps dashboards uniform and avoids scattering display flags through templates.
• Server-rendered time, client-side motion. Render the initial hand positions from a server-side timestamp (so the clock is correct on first paint and works without JS), then let a small Alpine/Livewire snippet advance the hands. This avoids a blank clock during hydration.
• Component composition. Wrap the package component in your own Blade component (e.g. x-ui.clock) that fixes sizing, theme colours and accessibility attributes. Your wrapper becomes the single place to adapt when the package's markup changes.
• Timezone-aware scheduling UIs. For admin panels showing multiple regions, render one analogue clock per timezone using the package's timezone option rather than converting dates in the controller. Keep the conversion in the package so DST is handled in one place.
• Testing. Freeze time with Carbon::setTestNow() and assert on the rendered component (assertSee, assertViewHas) rather than on pixel-level markup. For analogue output, assert the presence of the expected hand elements/attributes and the computed angles for a known timestamp.
• Integration tips. Register the package's asset bundle once in your layout rather than per component; if you use Vite, confirm whether the package ships publishable assets or expects them via CDN, and import accordingly.

Gotchas and Tips

• Timezone mismatch. The most common surprise is a clock that is correct in tests but off by hours in production because the package reads its own timezone setting rather than config('app.timezone'). Decide explicitly which one wins and set it in the published config.
• Server/client drift. A server-rendered timestamp plus a client-side tick can jump if the user's device clock differs. Derive subsequent positions from the server-supplied epoch, not from Date.now().
• DST transitions. Analogue hands make DST mistakes visually obvious (a hand jumping an hour). Test around a spring-forward boundary in a non-UTC timezone.
• Asset publishing after upgrades. New releases may add or rename published views/assets; re-publish and diff rather than blindly using --force, which overwrites your customisations.
• Compiled views. After changing a published clock view, run php artisan view:clear — stale compiled Blade is a frequent false alarm when the markup "didn't change".
• Accessibility. A purely visual clock conveys nothing to screen readers. Add a text time (visually hidden or aria-label) in your wrapper component; do not rely on the package to do this.
• Format config. 12/24-hour and locale settings often affect numerals/labels but not hand angles; confirm which options actually alter the analogue rendering before debugging CSS.
• Extension points. Prefer overriding the published view or binding a custom renderer in the container over editing vendor files; treat the config file and Blade component as the stable public surface.
• Debugging. If the clock renders digitally despite the config change, check for a cached config (php artisan config:clear) and for a component attribute overriding the config default.