Service Status Inspector Laravel Package

Getting Started

This is a standalone PHP library, not a Laravel package — there is no service provider, facade, or config file to publish. Add it with composer require smartassert/service-status-inspector:^6.0 (requires PHP 8.2+, which 6.0 enforces).

Look first at:

1. vendor/smartassert/service-status-inspector/README.md — the canonical usage example.
2. src/ — the inspector entry point and the value objects it returns (status + collection types). These are the only surfaces you'll typically touch.
3. composer.json — confirm the PSR-18/PSR-17 dependency constraints so your app's HTTP client version doesn't conflict.

First use case: a health-check command that takes a list of URLs your app depends on (payment gateway, internal APIs, search cluster) and reports which are reachable. Construct the inspector with an HTTP client, pass the URLs, iterate the returned statuses, and exit non-zero if anything is down.

Implementation Patterns

Construct the inspector from the container. Because the library expects a PSR-18 client (and PSR-17 factories for request creation), bind them in a service provider rather than new-ing Guzzle inline. Laravel's Illuminate\Http\Client is not PSR-18, so either resolve Guzzle from the container or use psr18 adapters — decide once and register a singleton.

Wrap it in an Artisan command, not a controller. php artisan services:status is the idiomatic entry point: build the URL list from config('services.monitored'), run the inspection, format a table with $this->table(), and return self::FAILURE when any status is not up. This makes it usable from cron, CI, and manually.

Schedule it and cache the result. Put the command on Schedule::command('services:status')->everyFiveMinutes() and write the outcome to the cache. Expose a cheap /health route that reads the cache instead of performing live HTTP calls on every request — you do not want a monitoring page that fan-outs to ten endpoints per hit.

Use the result objects, don't re-implement parsing. The returned status objects carry the URL and the availability outcome; treat them as an immutable DTO layer. Map them into your own array/JSON shape at the boundary (command output, API response) rather than leaking library types into controllers or jobs.

Fan out with a job for large URL sets. The inspector is synchronous. For dozens of endpoints, dispatch one CheckServiceStatus job per URL with Bus::batch() and aggregate, so a single slow host does not stall the whole run. Use Http::timeout()/client-level timeouts to bound each call.

Gate deployments on it. In CI or a deploy pipeline, run the command after migrations and before traffic switch; a non-zero exit is a natural readiness gate.

Gotchas and Tips

• 6.0 is a PHP-floor bump. The release is small (CS-fixer, PHPStan ^1.10, PHP 8.2/8.3 CI), but the effective breaking change is dropping support for older PHP. If you're still on 8.1, stay on 5.x — there is no feature reason to rush.
• PHPStan ^1.10 is a dev constraint, not runtime. It won't affect consumers, but if you extend or fork the package, note that analysis rules were tightened.
• No Laravel auto-discovery. Don't expect a facade. Any "package not found" error is almost always a missing container binding for the PSR-18 client.
• PSR-18 vs Guzzle direct. Passing a client that doesn't implement ClientInterface fails loudly; passing a Laravel HTTP client wrapper silently won't exist. Pin the adapter in one place.
• Timeouts and DNS failures surface as exceptions, not "down" statuses. Catch ClientExceptionInterface around the inspection call (or per-URL if you fan out) and translate exceptions into a "down" result yourself — otherwise a single unreachable host can abort the whole report.
• No retry, caching, or backoff built in. Wrap the call in retry() or your own backoff if you're monitoring flaky third parties; the library reports one observation per run.
• Extension point is the injected client. Need mocks in tests? Bind a fake PSR-18 client (or Mockery double) — there is no separate inspection interface to implement, so test at the client boundary.
• Keep the monitored URL list in config, not code. config/services.php + env overrides lets ops change targets without a deploy, and it keeps the package usage trivially testable.
• Watch the changelog for 7.0. This package moves in lockstep with PHP releases (5.0 → 6.0 was purely a PHP floor change), so expect the next major to track a future PHP version rather than new features.