Nova Ohdear Tool Laravel Package

Getting Started

1. Confirm you have the right package before you install it. The composer metadata for ohdearapp/nova-ohdear-tool says "display the application log," but the README, release notes, and integrations all describe an Oh Dear site-monitoring dashboard (uptime, SSL, broken links, cron checks). Read src/ once before composer require — a log viewer and a monitoring viewer have completely different setup steps (log path vs. API token) and different security footprints. If you actually want to tail laravel.log in Nova, this is the wrong package.

2. Install into an app that already has Nova working.

   composer require ohdearapp/nova-ohdear-tool
   

   The tool renders inside the Nova layout, so Nova's auth, sidebar, and theme all come for free. It has no meaning outside a Nova app.

3. Register the tool in app/Providers/NovaServiceProvider.php:

   public function tools()
   {
       return [
           new \OhDear\NovaOhDearTool\NovaOhDearTool(),
       ];
   }
   

4. Publish config/assets and clear caches:

   php artisan vendor:publish --tag=nova-ohdear-tool
   php artisan nova:publish
   php artisan config:clear
   

5. Wire the token. Put your Oh Dear API token where the published config expects it (typically OHDEAR_API_TOKEN in .env). Use a team-scoped token, not an org admin token — the tool only needs read access to the sites you want surfaced.

6. Open /nova and look for the new sidebar entry. That's the whole surface: a list of monitored sites with health indicators, and drill-downs into uptime, SSL, broken links, and scheduled jobs.

First use case: post-deploy sanity check. Open the tool, scan for anything non-green, click into the failing check, and jump to Oh Dear's own report for detail. Look first at the published config (token, cache TTL) and your NovaServiceProvider::tools() registration — those two places control almost all behavior.

Implementation Patterns

• Gate it behind canSee. Every Nova user sees registered tools by default. If you have PMs, support staff, or client-facing users in Nova, restrict the tool to ops:

  return [
      (new \OhDear\NovaOhDearTool\NovaOhDearTool())
          ->canSee(fn ($request) => $request->user()->hasRole('ops')),
  ];
  

• Register conditionally per environment. Staging should not show production uptime (and vice versa). Swap the token per environment and only register the tool where a token exists:

  return config('services.ohdear.token')
      ? [new \OhDear\NovaOhDearTool\NovaOhDearTool()]
      : [];
  

• Store the token in config/services.php, not env() inside the tool config. config:cache in production will silently blank out any env() call outside config files. Reference it as config('services.ohdear.token') from the published tool config.

• Push status onto the Nova dashboard. The tool page requires a deliberate click; the dashboard is what people actually look at. Register the package's card (or the tool as a card) so red status is visible on /nova before anyone navigates. This is the pattern that actually changes day-to-day behavior on a release day.

• Use it as a read-only viewer, not a workflow node. There are no migrations, no scheduled jobs, and no writes back to Oh Dear. Don't wire it into deploy pipelines or attempt to acknowledge/resolve incidents from it. Keep Oh Dear's own Slack/email alerting as the paging path — this tool is for "look before you leap" and "post-deploy confirm."

• Incident triage shortcut. Nova → tool → scan for red → Oh Dear's detail page → Telescope/Sentry for the app-level cause. The tool saves the context switch, not the investigation. Being explicit about that in a runbook prevents people expecting it to tell them why something is down.

• Fork it as a first-class dependency if you plan to keep it. Given ~29 stars, zero dependents, and an April 2021 last release, treat adoption as vendor and own: pin the version, copy it into packages/ as a path repository, and be prepared to patch the Vue component and tool registration yourself when you upgrade Nova.

Gotchas and Tips

• Nova version is the real gate. Last release was v1.1.4 (a cosmetic "tool page title" patch, #31) in April 2021, targeting Nova 3.x / PHP 7.x / Laravel 8. On Nova 4/5 expect composer constraint conflicts and Nova asset-registration breakage. Test in a branch, not against a shared admin panel.

• Description/name mismatch is not cosmetic. The composer description says log viewer; the package is an Oh Dear monitor. Confirm with the source which one you're getting before the security review, because "renders log file contents" and "calls a third-party API with a token" have very different threat models.

• A stale cached config is the #1 cause of "the tool doesn't show up." After editing the tool config or NovaServiceProvider, run:

  php artisan config:clear
  php artisan nova:publish --force
  

  Then hard-refresh the browser — Nova's compiled JS is aggressively cached.

• Blank or empty tool page? Check, in order: (1) the tool is actually in tools(); (2) canSee/authorize isn't returning false for your user; (3) the token is valid and the Oh Dear API is up (they publish a status page); (4) storage/logs/laravel.log for exceptions thrown during render — API failures typically surface as an unhandled exception or an empty state rather than a friendly error message.

• Rate limits and slow cold loads. The tool calls the Oh Dear API on render. With many sites and no caching, page loads get slow and you can brush against rate limits — especially if several people open the tool at once. If the published config exposes a cache TTL, tune it; otherwise plan to add Cache::remember when you fork.

• Token handling is your responsibility. The published config may land in version control with a placeholder — never commit a real token into it. Keep the real value in .env or a secret manager, scope it to the team whose sites you want visible, and rotate it like any other credential.

• Extension points are thin by design. The knobs are: the published config (token, caching) and canSee/authorize. Anything richer — filtering by team, per-check detail pages, alerting hooks, a custom card layout — means editing the Vue component in a fork. Budget for that up front if the out-of-the-box UI doesn't match your needs.

• No community support. Zero dependents and ~29 stars means no blog posts, no StackOverflow answers, no issues triage. The tool class, the Vue component, and the config file are the documentation. Read them once and keep notes in your fork's README.