Laravel Sitesmonkey Laravel Package

Getting Started

Install and publish

composer require monkeysoft/laravel-sitesmonkey
php artisan vendor:publish --tag=sitesmonkey-config

Laravel's package auto-discovery should register the service provider; confirm with php artisan about or check bootstrap/cache/packages.php if the config keys come back null.

Where to look first, in this order:

1. config/sitesmonkey.php — the published config is the source of truth for the API endpoint, key, and which monitoring features are enabled. Read every comment; this package's defaults determine whether it is passive (reporting only) or active (middleware/scheduling).
2. The package's src/ directory — with zero dependents and no public issue history, the source is the documentation. Look for the service provider's register()/boot() to see what it binds, and for any Console/ commands it registers.
3. README.md on the repo for the canonical env var names (typically SITESMONKEY_KEY / SITESMONKEY_ENABLED).

Your first use case: a heartbeat.

Before wiring up request-level monitoring, prove connectivity with the smallest possible surface. Drop the credentials into .env, then run whatever the package exposes as a health check — usually an artisan command like:

php artisan sitesmonkey:ping

If that command doesn't exist, call the package's client directly from php artisan tinker to validate the key and endpoint separately from Laravel integration. Getting a 200 here first means every later failure is a wiring problem, not an auth problem.

Implementation Patterns

Environment-gated enablement. Never rely on the package to detect environment for you. Add an explicit kill switch and check it in your own code:

// config/sitesmonkey.php
'enabled' => env('SITESMONKEY_ENABLED', false),

Set it true only in staging/production. This is the single most valuable line in the config — it makes local and CI runs deterministic and keeps your test suite off the network.

Middleware for request monitoring. If the package ships middleware, register it globally only after measuring. Prefer targeted registration so you control the blast radius:

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Monkeysoft\SitesMonkey\Http\Middleware\MonitorRequest::class);
})

If it is not global by default, that is a deliberate design choice — respect it and attach it to the specific route groups you actually care about (public web routes, API health endpoints) rather than the whole stack.

Heartbeats from the scheduler. The highest-value, lowest-risk integration is a scheduled ping that proves the scheduler itself is alive:

// routes/console.php
Schedule::command('sitesmonkey:ping')->everyMinute()->withoutOverlapping();

This catches the failure mode uptime monitors miss: the app responds, but cron/queue/scheduler is dead. Add withoutOverlapping() — a stuck ping is itself a signal, and you don't want a backlog of them.

Exception reporting via the handler. Rather than replacing your log stack, treat SitesMonkey as a notification channel. Hook it into bootstrap/app.php's withExceptions so it fires alongside — not instead of — your existing reporting:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (Throwable $e) {
        app(\Monkeysoft\SitesMonkey\Client::class)->reportException($e);
    });
})

Verify the actual class/method against src/ before shipping — this is the integration point most likely to differ from what you'd assume.

Separate your signals. In practice, split monitoring into three independent calls so a failure in one doesn't mask the others:

• Uptime — the scheduled ping.
• Errors — exception handler hook.
• Business health — a custom check you push manually (failed jobs count, stale records, queue depth). Wrap this in a small service class of your own so the package remains a transport detail, not a domain concern.

Deployment marker. If the package exposes a release/version parameter, set it from your deploy script (GIT_SHA or a release tag) so dashboards can correlate regressions with deploys. This costs one env var and saves hours during incident review.

Gotchas and Tips

Silent failure is the default mode — and usually the right one. Monitoring integrations must never take down the app. Expect (and verify) that HTTP calls to SitesMonkey are wrapped in try/catch and short timeouts. Check the package's Guzzle/HTTP client config: if the timeout is the default (often none or 30s), a SitesMonkey outage becomes your outage. Override it to 2–3 seconds if the config exposes it; if it doesn't, that's an extension point worth patching or wrapping.

Config caching will bite you. After editing config/sitesmonkey.php or .env, run:

php artisan config:clear && php artisan config:cache

A stale config:cache is the most common reason "the key is set but it's not reporting." Similarly, in containerised deploys the env vars must be present at cache build time, not just at runtime.

Middleware ordering matters. If the package's middleware runs after StartSession/Authenticate, it can log user context; if it runs before, it can't. Decide what you need and position it explicitly. Also check whether it terminates (terminate()) or blocks in handle() — a blocking HTTP call in handle() adds latency to every request, which is unacceptable on a hot path.

Sample in high-traffic apps. Per-request monitoring multiplies your outbound request volume. If there's no built-in sampling rate in the config, implement one. A 5–10% sample on a busy app gives you the same signal quality at a fraction of the overhead.

Disable it hard in tests. Add to phpunit.xml or your test bootstrap:

<env name="SITESMONKEY_ENABLED" value="false"/>

Without this, every test that touches an instrumented route makes a real network call — slow, flaky, and potentially noisy for whoever owns the SitesMonkey account.

Pin the version. With zero stars and zero dependents, the API surface is not battle-tested and minor releases may move. Use "monkeysoft/laravel-sitesmonkey": "~1.0" or an exact constraint, and read the diff on each bump. Budget a small amount of time to read the source of any version you upgrade to.

Debugging checklist, in order: (1) is enabled true in the cached config? (2) does the artisan ping command return non-error? (3) is the provider actually discovered (php artisan about)? (4) does the middleware appear in php artisan route:list -v? (5) are outbound requests to the endpoint blocked by egress firewall rules — common in locked-down production VPCs.

Extension point to plan for. Keep the package behind a thin interface of your own (App\Support\Monitoring). When you eventually add a second monitor, change providers, or need to no-op monitoring in a specific context, you change one class instead of grepping for package calls across the codebase. This is worth doing even for a package you expect to keep — especially for one this young.