Healthcheck Laravel Package

Getting Started

The 1.1.2 release adds a client entry to the package configuration, which means the client instance is now built from config rather than being hard-coded or resolved ad hoc. Start with the config file — it is the primary control surface for the package.

composer require vendor/package
php artisan vendor:publish --tag=package-config

Open config/package.php and look at the new client key first. Set its values from your .env rather than editing the published file directly, so per-environment overrides stay out of version control churn.

First use case: resolve the client from the container instead of constructing it yourself.

use Vendor\Package\Client;

public function __construct(private Client $client) {}

public function __invoke()
{
    return $this->client->request(...);
}

Because the client is now config-driven, this constructor injection is the supported path — the container reads config('package.client') and wires the instance for you. If you have existing code doing new Client(...) or app()->make(Client::class, [...]) with manual arguments, migrate it now; those arguments are very likely redundant.

Implementation Patterns

Constructor injection over container lookups. Type-hint the client in controllers, jobs, listeners, and console commands. This is what makes the config-driven construction worth having — swapping config values propagates everywhere without touching call sites.

Per-context clients via config overrides. Since the client is described by config, you can create differently-configured instances by temporarily overriding before resolution:

$client = tap(config(['package.client.timeout' => 2]), fn () => app(Client::class));

Useful for one-off long-running operations that need a larger timeout, or for multi-tenant setups where credentials differ per tenant. If the package registers the client as a singleton, remember this only works before first resolution (see Gotchas).

Bind your own implementation. Register a binding in a service provider to substitute a subclass or a test double:

$this->app->bind(Client::class, fn ($app) => new Client($app['config']->get('package.client')));

This is the cleanest extension point when you need to add logging, metrics, or header injection without forking the package.

Queue and HTTP-test friendly usage. Wrap calls in a small application-level service that owns retries and error mapping, keeping the package client as a thin transport. In tests, combine Http::fake() with a config override so you exercise the real construction path while stubbing the wire.

protected function setUp(): void
{
    parent::setUp();
    config(['package.client.base_url' => 'https://api.test']);
    Http::fake([...]);
}

Treat config as a typed boundary. Validate required keys in a service provider with a clear exception message, so a missing environment variable fails loudly at boot rather than as a confusing error deep in the client.

Gotchas and Tips

• Published configs do not get new keys. This release adds client to the package's default config. If you published config/package.php before 1.1.2, your local copy has no client key. Either republish (php artisan vendor:publish --tag=package-config --force, then reconcile with version control) or rely on the package's mergeConfigFrom and confirm the defaults are actually merged. Check this first if the client resolves as null or throws after upgrading.
• Clear the config cache. php artisan config:cache is common in staging and production. Any change to the new client block requires php artisan config:clear followed by a re-cache, otherwise you will debug a config value that is not the one being read.
• Never call env() outside config files. Put environment lookups in config/package.php only. After config:cache, env() returns null everywhere else — a classic post-deploy failure when the new client settings are read directly.
• Watch for a singleton binding. If the client is bound as a singleton, its state (cookies, auth token, accumulated headers) persists across requests within a single worker. This bites in Octane, Horizon, and tests. Reset it in setUp() with $this->app->forgetInstance(Client::class) or bind it as a transient if the package allows.
• Config is read at resolution time. config()->set() after the client has already been resolved has no effect on an existing instance. In tests, override config before the first resolve.
• Debug with the container, not guesses. php artisan tinker, then config('package.client') and app(Client::class) — inspect the actual resolved object and its constructor arguments. If they look wrong, the problem is the config file, not the package.
• Prefer overriding config over editing vendor defaults. Keeping client values in .env and a thin app-level config file means upgrades like this one are a composer update plus, at most, a republish — not a merge conflict.