Site Monitor Laravel Package

Getting Started

v1.1.0 is the first stable release, closing out a 46-beta run (v1.1.0-beta.46 → v1.1.0). Treat this as the point where the public API, config keys, and published migrations are safe to build against — previously you'd have been pinning beta tags and re-reading the changelog on every bump.

Minimal path to a first check:

1. composer require capell-app/site-monitor — on a fresh install you'll get ^1.1; if you were on a beta, update the constraint rather than leaving 1.1.0-beta.46 pinned.
2. Publish the package assets (vendor:publish with the site-monitor provider tag) — config and migrations. Read the published config file first; it's the best map of what the package can do and is the file you'll be editing most.
3. php artisan migrate to create the site/check tables.
4. Register one site (model create, seeder, or the Capell admin UI if you're in a Capell app) pointing at something cheap and reliable — your own /up health endpoint is the ideal first target.
5. Wire the check command into the scheduler and run it once by hand before trusting cron.
6. Add a notification channel to yourself only, and confirm you actually receive an alert when you point a site at a URL that 500s.

First real use case: monitor the marketing site, the API health endpoint, and one critical customer-facing integration per environment, alerting into a single Slack channel. Don't start by monitoring everything — you'll drown in noise before you've tuned thresholds.

Implementation Patterns

Seed sites, don't click them in. Registering monitored sites in a seeder (or a config-driven sync command) keeps local/staging/production consistent and makes the table reproducible. Environment-specific URLs should come from config() / env, not hardcoded rows.

Separate the "what" from the "how often". Store per-site interval/timeout rather than relying on a single global schedule. A 5-minute cadence is right for a checkout flow and wasteful for a brochure page. Run the scheduler every minute and let the package decide what's due — that's more robust than one cron entry per site.

Pair it with a dashboard, not just alerts. Persisting check results is only half the value; uptime percentage and response-time trend queries against the checks table are what you show stakeholders. Build a small read-only controller or Filament/Capell resource over the history rather than screen-scraping the package's own output.

Notifications: route by severity, not by site. A single "everything" channel gets muted within a week. Pattern that holds up: one channel for downtime, a separate low-priority one for degraded latency, and no channel at all for informational checks. Where the package exposes notification hooks, extend the base notification so you can add runbook links and on-call mentions.

Make it observable from day one. Log check failures with the site identifier and the failure reason. When an alert fires at 03:00, the first question is always "is this the site or the monitor?" — a failing DNS lookup from your worker looks identical to a dead site unless you log the distinction.

Local development. Disable outbound checks in testing/local or point them at localhost fixtures. Nothing burns trust in a monitor faster than a staging box that pages the on-call because it can't reach production-only hosts.

CI usage. A single "check all sites, fail the build on any non-2xx" invocation makes a decent post-deploy smoke test, especially if you scope it to the sites you just shipped.

Gotchas and Tips

• Upgrading from a beta is not guaranteed drop-in. The 1.1.0 changelog link is the whole release body — read the diff between beta.46 and 1.1.0 before bumping, and check whether config keys or migration columns were renamed during stabilisation. Publish-tag updates don't overwrite existing config, so a stale config/site-monitor.php can silently miss new options.
• Config cache bites. After changing the config in production, php artisan config:cache — but also remember the reverse: a cached config means edits to the published file appear to do nothing until you re-cache. Same for the scheduler.
• Overlapping runs. If the scheduler fires every minute and a batch of slow sites takes longer than the interval, you get pile-ups and duplicate alerts. Use withoutOverlapping() on the scheduled task and set per-check timeouts well below the interval.
• Flapping generates alert storms. A site that oscillates around a threshold will notify on every transition. Prefer N-consecutive-failures before alerting, and think hard before adding per-attempt notifications.
• Unbounded table growth. Check-result tables grow fast — 5 sites at 1-minute intervals is ~2.2M rows/year. Schedule the package's prune command (or write one) and decide your retention window early, because retrofitting a prune command onto a 40GB table is a bad afternoon.
• Worker environment ≠ web environment. Checks run from wherever the scheduler/queue runs, so DNS, egress firewalls, and TLS trust stores differ from your web nodes. A site that's fine in the browser and "down" from the worker is usually an egress problem, not an outage.
• Alert on the monitor itself. If no checks have been recorded in the last hour, that's a monitoring failure — surface it. A silently dead scheduler is worse than no monitoring, because everyone assumes they're covered.
• Timezones and Carbon. Response-time and uptime aggregations are easy to get subtly wrong across DST boundaries. Store UTC, aggregate in UTC, and only convert at render.
• Extension points. The stable release means subclassing the check/notification classes is now a reasonable long-term bet; before 1.1.0 you risked breaking on each beta bump. Keep your overrides in app/, not by editing vendor files, so future minor releases stay painless.
• Pin with care. ^1.1 is right for the stable line. If you must stay on a beta for a specific fix, isolate it and open an issue — betas are no longer maintained now that 1.1.0 shipped.