Verbose Error Http Client Laravel Package

Getting Started

1. Install the package:

   composer require superbrave/verbose-error-http-client
   

2. Check composer.json constraints first. Release 2.2.0 moves the Symfony/Anamnesis dependency line from 7.4.* to 8.x; confirm your Laravel/Symfony component versions are compatible before upgrading.
3. Look first at:
   • README.md for the intended client/exception usage.
   • The package service provider or container bindings, if present.
   • The exception classes and response formatting logic, since that is the package’s main value.
   • Tests or fixtures showing expected verbose error output.
4. First use case: wrap an outgoing HTTP call in development/staging so failed responses include enough request/response context to debug quickly, instead of only showing status codes.

Minimal Laravel-style usage:

use Superbrave\VerboseErrorHttpClient\VerboseErrorHttpClient;

$client = app(VerboseErrorHttpClient::class);

try {
    $response = $client->request('GET', 'https://api.example.com/users');
} catch (\Throwable $e) {
    report($e); // or log the verbose message locally
}

If the package exposes an interface/contract, bind it in a service provider and inject that instead of constructing the client directly.

Implementation Patterns

• Constructor injection: inject the verbose client into services, jobs, or action classes. Avoid resolving it from the container inside domain code.
• Wrap only unreliable integrations: use this around third-party APIs where response bodies and request context matter for debugging, not for every internal HTTP call.
• Decorate the standard HTTP client: if the package wraps Symfony HttpClient, keep the normal client interface in your application and swap in the verbose implementation via the container.
• Pair with retries: use Laravel/Symfony retry middleware around idempotent requests, but log the verbose exception only after final failure to avoid noisy duplicate logs.
• Sanitize before logging: verbose error messages may include request bodies, headers, or response payloads. Redact authorization tokens, cookies, passwords, and personal data.
• Environment-aware usage: enable verbose exception output in local/staging. In production, log a redacted version or map the exception to a safer application exception.
• Test with fakes: use Laravel Http::fake() or Symfony mock responses to assert that failed responses produce useful exception messages without hitting real APIs.
• Centralize error mapping: convert package exceptions into your app’s domain exceptions at the service boundary so controllers and jobs do not depend directly on package details.

Example binding:

// AppServiceProvider::register()
$this->app->bind(
    \Superbrave\VerboseErrorHttpClient\VerboseErrorHttpClient::class,
    fn ($app) => new \Superbrave\VerboseErrorHttpClient\VerboseErrorHttpClient()
);

Example service usage:

final class UserApi
{
    public function __construct(private VerboseErrorHttpClient $client) {}

    public function find(int $id): array
    {
        $response = $this->client->request('GET', "https://api.example.com/users/{$id}");

        return $response->toArray();
    }
}

Gotchas and Tips

• Symfony 8 dependency bump: 2.2.0 is mainly a dependency upgrade. Treat it as potentially breaking if your app still requires Symfony 7.4.* components. Run composer why-not superbrave/verbose-error-http-client 2.2.0 if the update is blocked.
• PHP/runtime compatibility: Symfony 8 typically raises PHP/platform requirements. Verify your CI matrix, production PHP version, and Laravel version before deploying.
• No obvious new API: the release notes do not describe new features or deprecations, so avoid assuming new configuration options exist. Re-read the README after upgrading.
• Secrets leakage: verbose errors are useful precisely because they include more context. Never expose them directly to end users or untrusted logs without redaction.
• Large or streamed responses: reading a response body to build an error message can be expensive or impossible for streamed responses. Check how the package handles non-seekable streams and large payloads.
• Exception hierarchy: catch the package’s specific exception if available, but keep a broader fallback at integration boundaries. Do not let package-specific exceptions leak into controllers.
• Retry interaction: retries may hide the first verbose error. Log attempts separately if the final error is not enough to diagnose intermittent failures.
• Config caching: if the package publishes config, run php artisan config:clear locally and php artisan config:cache in deployment after changing config.
• Extension points: look for custom formatters, exception factories, middleware, or container bindings. Prefer extending those over forking the package.
• Upgrade workflow: run the full test suite, test one real failed HTTP call in staging, and inspect the generated exception message for useful but safe output.