Cached Http Client Bundle Laravel Package

Getting Started

• Install the package with Composer and check the package README/examples first; this is a small 0.x package, so the README and tests are the most reliable API reference.
• Note that despite the “bundle” name, this is a Symfony-style bundle rather than a native Laravel package. In Laravel, plan to bind the cached client and cache pool manually in a service provider; in Symfony, register the bundle and configure its cache service.
• Minimum viable setup: configure a PSR-6/PSR-16 cache pool, wire the cached HTTP client to use it, then replace direct HttpClientInterface calls for slow or rate-limited third-party GET requests.
• First use case: cache an idempotent external API lookup (e.g. currency rates, geo data, catalog metadata) for a short TTL and verify that repeated calls return the cached response instead of hitting the remote service.
• Start with a single endpoint and a conservative TTL. Confirm cache hits/misses before rolling the client out across multiple integrations.

Implementation Patterns

• Inject the cached client rather than the raw HTTP client wherever the call is cacheable. Keep a separate raw client for writes, authenticated user-specific calls, and anything that must never be cached.
• Use the client for idempotent GET/HEAD requests by default. Avoid caching POST/PUT/PATCH responses unless the remote API explicitly defines cache semantics and you control the cache key.
• Build cache keys from the full request identity: method, URL, normalized query string, and relevant Vary headers such as Authorization, Accept-Language, or tenant identifiers.
• In Laravel, register the client as a singleton in a service provider and inject it into services/jobs. In Symfony, rely on autowiring and bundle configuration.
• For testing, bind an in-memory/array cache adapter and a mocked HTTP client so cache-hit and cache-miss paths are both exercised.
• Use short TTLs for volatile data and longer TTLs for reference data. If the package supports stale responses, consider a stale-while-revalidate pattern for latency-sensitive endpoints.
• Add observability around the client: log cache hits/misses and remote request duration. This makes TTL tuning and cache-key debugging much easier.
• For multi-tenant or per-user APIs, either bypass the cache or include the tenant/user identity in the cache key. Do not share cached responses across security boundaries.

Gotchas and Tips

• v0.2.0 breaking change: the deprecated request function was removed. Update any callers that still use the old method and audit for code relying on the previous client return behavior.
• v0.2.0 behavior change: the client now creates a cacheable response. Verify how your application consumes the returned response—especially if you read the body multiple times, stream it, or type-hint a specific response class.
• This package is still pre-1.0. Pin the version in composer.json and review release notes before upgrading; minor versions may contain breaking API changes.
• Cache poisoning is the main risk: authenticated responses, personalized data, and headers not included in the cache key can leak between users. Default to bypassing the cache for authenticated requests unless you have explicitly designed the key.
• Be careful with large or streaming responses. Caching them can increase memory usage and storage costs; prefer caching small JSON payloads.
• Debugging cache misses usually comes down to key mismatches. Log the generated key and confirm that query parameter ordering, trailing slashes, and headers are normalized consistently.
• Clear the relevant cache pool after config or key-strategy changes; otherwise old entries may continue to be served under the previous assumptions.
• Extension points to watch: custom cache pool configuration, client factory/service decoration, and response wrapping. Prefer decorating the package client over forking it so future upgrades remain manageable.
• If using Laravel config caching, ensure any custom client/cache configuration is cache-safe and does not rely on runtime-only values.