Probe Laravel Package

Getting Started

Reality check on v0.0.5 first: the release notes for v0.0.5 are a bare changelog link (v0.0.3...v0.0.5) with no described changes. Before adopting, read the actual diff on GitHub and the README.md on the tag you intend to install — at 0.0.x nothing in the semver contract protects you from breaking changes in a patch bump.

Minimal install path:

1. composer require morcen/probe — pin it ("morcen/probe": "0.0.5") rather than floating on ^0.0, because 0.0.x releases can and do move the API surface.
2. Publish the package config (php artisan vendor:publish --provider="Morcen\Probe\ProbeServiceProvider" or the --tag=probe-config variant — check the README for the exact tag) and read every key. This file is the best documentation the package has.
3. Inspect src/ for the service provider, the facade/entry class, and any Contracts/ directory. If there is a Probe contract or ProbeResult-style value object, that is your extension point for custom checks.

First use case: wire it up as a single health/diagnostics endpoint you can hit from your load balancer or uptime monitor, then grow from there. Don't start by writing custom probes — get the stock checks returning a response you can curl first, confirm the shape of the payload, and only then start extending.

Where to look when the README is thin (likely at this version):

• src/ — the actual public API. Treat method signatures here as the source of truth, not the docs.
• The published config/probe.php — which checks are enabled by default, and whether the route is auto-registered.
• tests/ in the package repo — the fastest way to see intended usage.
• CHANGELOG.md at the tagged commit — if it exists, it will say more than the GitHub release body did.

Implementation Patterns

Route registration. Most packages of this shape either auto-register a route or expect you to. If it auto-registers, immediately decide whether you want that: gate it behind a middleware group and, ideally, a config flag per environment so it is never anonymously reachable in production. A common pattern is to disable the package route entirely and expose your own thin controller:

Route::get('/health', HealthController::class)
    ->middleware(['throttle:60,1']);

…which internally calls the package's runner and maps the result to a status code. This keeps the URL, auth policy, and caching under your control instead of the package's.

Two invocation modes. Distinguish between:

• Synchronous, on-request probes — fine for cheap checks (DB SELECT 1, cache roundtrip, disk space, queue depth). Keep the total under a second; anything slower will eventually page you for the wrong reason.
• Scheduled/background probes — for expensive or third-party checks (Redis, S3, mail provider, external HTTP APIs). Run these on a schedule, persist the result, and have the HTTP endpoint serve the last known state. This avoids turning your health endpoint into a dependency amplifier: if the mail provider is slow, your Kubernetes liveness probe shouldn't kill the pod.

Custom probes. Subclass or implement whatever contract src/Contracts exposes, then register it in config (array of classes) or the provider's extend/register method. Keep each probe single-purpose and returning a structured result rather than throwing — a throw is an outage signal, a failed result is a status. Wrap third-party probes in their own timeout so a hanging socket can't block the request.

CI and deploy integration. The highest-value day-to-day use is as a post-deploy smoke test: hit the endpoint after artisan migrate --force and fail the pipeline on a non-200. Pair it with a php artisan probe command if the package ships one (check src/Commands/) — being able to run the same suite locally on demand is a large debugging win.

Environment tiers. Typically you want three levels: a lightweight liveness check (process is up, no dependencies), a readiness check (DB + cache reachable), and a full diagnostics report (everything, including third-party, authenticated, never public). Map these to config presets rather than maintaining separate code paths.

Gotchas and Tips

Pin the version. 0.0.3 → 0.0.5 is two releases with a silent changelog. In Composer, ^0.0.5 constrains to 0.0.x and will happily pull 0.0.9 with breaking changes. Use an exact constraint and bump deliberately.

Config caching will bite you. Any probe registration done inside a closure in a config file, or driven by env() calls at runtime, breaks under php artisan config:cache. Resolve env values in the config file only, and register probes from a service provider — not from config callbacks.

Route caching. If the package auto-registers routes via the provider, a stale route:cache after upgrading can leave you with a 404 where the health endpoint used to be. Clear both caches as part of the upgrade step and make the endpoint a deployment verification item.

Don't expose it. The default in a lot of pre-1.0 packages is an unauthenticated route on / or /health. That leaks database names, versions, and dependency topology. Check, then explicitly lock it down — auth middleware, IP allowlist, or a shared secret header.

Timeouts or nothing. Every probe touching I/O needs an explicit timeout. A health check that can block indefinitely is worse than no health check: it converts a partial outage into a cascading one as your monitor's connections pile up.

Status codes are your contract. Decide now what maps to 200 / 503 and write it into your monitor config. Changing that mapping later silently breaks alerting. If the package returns 200 with a failure body, that is a classic pre-1.0 footgun — normalise it in your controller.

Debugging checklist when a probe misbehaves: php artisan tinker the runner directly to separate "probe is broken" from "route/middleware is broken"; then run with the config cache cleared; then check whether the failure is in your custom probe or a stock one by disabling yours in config.

Extension points worth knowing: the config array of probe classes, any contract in src/Contracts you can implement, the service provider's boot method for adding routes/middleware, and (if present) a facade for ad-hoc invocation outside of HTTP. Also check for events dispatched around probe completion — an event listener is the cleanest place to forward failures to Slack/PagerDuty without forking the package.

Given the 0.0.x state, budget for an upgrade cost each time you bump, and consider wrapping the package behind your own small HealthService class. That interface layer costs an hour now and means the next breaking release touches one file instead of every controller.