Statamic Vitals Laravel Package

Getting Started

Install and confirm it registers. This is a Statamic addon, so installation is a Composer bump plus Statamic's addon auto-discovery — there is no manual service-provider registration in config/app.php.

composer require marcorieser/statamic-vitals:^1.3.0

Pin ^1.3.0 if you are on (or heading to) Statamic v6; stay on ^1.2 for v5 sites until the v6 upgrade is sequenced. After install, clear caches so Statamic picks up the addon manifest and any new CP assets:

php artisan cache:clear
php artisan view:clear
php artisan statamic:stache:clear   # if the addon touches the Stache

Where to look first. In order:

1. vendor/marcorieser/statamic-vitals/config/ — the package's default config. This is the contract: which checks run, how they're grouped, and what the extension point looks like. Read it before you publish anything.
2. The addon's source for the check classes — one class per check, each returning a pass/warn/fail result. That class shape is what you'll copy when you write your own.
3. The control panel dashboard — add the Vitals widget via the CP's widget picker, or define it in config/statamic/cp.php under widgets if you want it to appear for every user by default.

First use case. Get the widget onto your dashboard before you get it onto anyone else's. Open the CP, confirm each check reports the state you expect (PHP version, environment, cache driver, storage writability, queue health), then decide which results actually matter for your site. The value here is not "green checkmarks" — it's that a red cache or queue result on a Monday morning tells you about a broken deployment before an editor files a ticket.

Implementation Patterns

Publish and own the config. Zero-config defaults are fine for a first look, but publish the config and commit it so check behaviour is reviewable in diffs:

php artisan vendor:publish --tag=statamic-vitals-config

Then treat the published file as code: the checks enabled in production should not be the same set you run locally (storage thresholds, queue expectations, and environment assertions all differ).

Environment-scoped checks. The most common day-to-day pattern is making the check list config-driven per environment — strict in production (queue must be running, storage must be writable, APP_DEBUG must be false), lenient locally (skip queue checks if you're not running a worker). Do this through the config rather than by commenting out widget code.

Custom checks. The addon advertises an extensible architecture, so the intended pattern is: find the check contract (an interface or abstract class in the package source), implement it, and register your class in the published config's checks array — or via whatever registration hook the package exposes if it isn't purely config-driven. A pragmatic custom check looks like:

final class SearchIndexFreshCheck implements VitalsCheck
{
    public function run(): VitalsResult
    {
        $stale = Cache::get('search:last_sync');

        return $stale && $stale->gt(now()->subHours(6))
            ? VitalsResult::pass('Search index synced within 6h')
            : VitalsResult::warn('Search index stale — last sync: ' . ($stale ?? 'never'));
    }
}

Keep custom checks cheap and side-effect free. The dashboard renders them on page load; a check that queries an external API or walks the filesystem synchronously will make the CP feel slow and will be the first thing you regret.

External monitoring. The package's premise is exposing vitals "for external usage" — so the second integration pattern is wiring the results into something outside the CP: an uptime monitor, a status page, or a scheduled Slack ping. Verify in the source whether that means a route/endpoint or just a programmatic API you call from your own command. If it's a route, it must be behind auth or an IP allowlist — a public endpoint that reports your PHP version, environment name, and queue state is a reconnaissance gift.

Deploy-time smoke test. If the checks are callable outside the CP (a facade, a service class, or an artisan command), add them to your post-deploy script or a staging smoke test. Failing the deploy when APP_DEBUG is on in production is worth more than any dashboard.

Gotchas and Tips

• Cache-backed checks lie after deploys. If a check reads cached state (queue heartbeat, storage probe, a "last synced" marker), it will report stale on the first request after a deploy or cache flush. Make cache-clearing an explicit step in your release runbook, and design custom checks to report "unknown" rather than "fail" when the cache is cold.
• Queue checks depend on a worker actually running. In a multi-server or container setup, "queue is healthy" may only mean this node's view. Understand which host is being inspected before you alert on it.
• Storage and cache checks assume your default drivers. If you've got a non-default disk or a cache store that doesn't support the operations the check performs (e.g. a check that assumes tag support), expect a false fail. Configure the check to point at the disk/store you actually care about rather than overriding the app default.
• Dashboard widget ≠ monitoring. The widget is a manual, human-triggered glance. It does not page anyone. If you need alerting, that's your own scheduled job calling the checks — budget for it rather than assuming the addon covers it.
• Widget visibility is a permissions question. Anyone with CP access can typically see the dashboard. Environment name, PHP version, and driver names are low-grade but real information disclosure; if you have external editors, confirm who can see the widget before enabling it globally via cp.php.
• Publishing config shadows future updates. A published config file wins over the package default forever. When you bump the addon, diff your published config against vendor/.../config/*.php — new checks or renamed keys won't appear automatically.
• Version pinning is the real operational decision. v1.3.0 exists to support Statamic v6. Confirm from composer.json whether v1.3.0 widens the constraint to allow v5 and v6 or replaces v5 support entirely — that determines whether v5 sites can take patch fixes. Keep the pin explicit in every site you own rather than floating on *.
• After a Statamic major, smoke-test the widget specifically. Addon compatibility releases are often just constraint changes. Load the dashboard, confirm every check still resolves and no CP asset breaks — runtime failures here are silent in CI.
• Extension points beat forks. If a check is wrong for your infrastructure, the right move is a custom check class registered in config, not a patch to vendor/. Keep vendor/ pristine so upgrades stay one-line.
• Low bus-factor. Single maintainer, low star count. Fine as a read-only diagnostic widget; be cautious about making it load-bearing in an alerting path without pinning and testing.