Php Request Class Laravel Package

Product Decisions This Supports

• Build vs. buy for outbound HTTP integration layers. This package (v2.0.0) is the "request class" abstraction: one class per upstream API, with built-in Guzzle transport, response caching, structured log files, and hooks (parseResponseString(), postProcess(), responseFromCache(), log()). It is a decision to standardize third-party integrations rather than hand-rolling clients per service.
• Observability roadmap for integrations. The headline change fixes a real defect (issue #35): on a cache miss, the log entry is now written after parsing and post-processing, so a downstream parse failure is recorded as a failure with its exception and getExtendedData()/->errors(), instead of looking like an unremarkable success. This directly improves debugging and incident triage for every integration built on the package — a genuine product-quality win, not just internal plumbing.
• Cache-hit telemetry. log() is now invoked on every outcome, cache hit or miss, with a default guard on responseIsFromCache. Previously cache hits were silently unlogged. This enables cache-hit-rate reporting and cost/latency attribution per integration — useful if we plan to expose upstream dependency health or caching ROI to stakeholders.
• Upgrade scoping and sequencing. This is a major version with behavioral breaking changes for subclasses. It changes when log() fires and what it receives. Any team-owned request class that overrides log() without calling parent::log() will begin logging on cache hits, and any postProcess() that rejects with a non-Throwable, non-JSON-serializable value can now cause the entire log write to abort — masking the real error with a logging exception. This is a risk item that must gate the upgrade, not a footnote.
• Data-handling and compliance review. Parsing/post-processing exception messages and getExtendedData() now land in the same log entry as the response body. If any of that can contain PII, tokens, or internal identifiers, we have a new data-exposure surface in log storage and log-shipping pipelines. This is a privacy/compliance decision, not purely engineering.
• Log-consumer compatibility. Transfer-level failures (BadResponseException/RequestException) may now contain the response body twice — once standalone, once nested in the stringified exception. Any dashboards, alerting rules, log parsers, or tests that structurally parse log files (e.g. counting blank-line-delimited sections) need revisiting.
• Roadmap signal — API hardening. The release notes explicitly recommend rejecting only with Throwable and suggest simplifying cache-hit logging by overriding log() directly instead of responseFromCache(). That is directionally a tightening of the extension contract; expect future majors to enforce it. Plan extension points accordingly rather than investing in the legacy responseFromCache() pattern.

When to Consider This Package

Adopt / upgrade when:

• You have (or are accumulating) multiple outbound third-party HTTP integrations and want a single, opinionated shape for transport, caching, and logging instead of N bespoke clients.
• You need per-request structured log artifacts with request/response/outcome/transfer-stats in one place, and you specifically need accurate outcome logging on downstream parse/post-process failures (the v2.0.0 fix).
• You want cache-hit visibility for cost/latency analysis, now that log() fires on cache hits.
• You can absorb a coordinated audit: grep all log() overrides, verify parent::log() or an explicit responseIsFromCache guard; verify every postProcess() rejects only with Throwable; review exception payloads for sensitive data; update structural log-parsing tests.

Look elsewhere / defer when:

• You only have one or two trivial HTTP calls — a thin Guzzle wrapper or Laravel's Http facade is lower overhead than adopting a class hierarchy and its extension contracts.
• You have a large, distributed set of request classes with heavy log()/postProcess() overrides and no reliable inventory — the migration audit is the real cost, and v2.0.0's failure mode (a non-Throwable rejection silently wiping the entire log entry) is a nasty one to discover in production.
• Your log pipeline is strictly schema-parsed downstream and you cannot tolerate duplicate response bodies or new appended sections without a coordinated consumer-side change.
• Strict log-hygiene/compliance constraints make it unacceptable to have parse/post-process exception payloads co-mingled with response bodies — until you've confirmed those payloads are safe to persist.
• You need guaranteed at-most-once or transactional logging semantics; the logging path can abort via array_map(stringify_body, ...) outside its own try/catch, so logging is best-effort, not durable.

How to Pitch It (Stakeholders)

For executives: This is a major-version upgrade to the shared request-class library that standardizes how we call external APIs. It fixes a real defect where failed responses were being logged as successes, which has been actively misleading our incident response. It also gives us cache-hit visibility we didn't have, supporting cost and latency analysis on third-party dependencies. The cost is a bounded, well-documented migration audit across our own request classes — no new infrastructure, no vendor spend.

For engineering: v2.0.0 moves the log() call site so it runs after parseResponseBody()/postProcess(), meaning log entries now reflect the true outcome including exceptions and getExtendedData(). It also calls log() on cache hits. Six concrete audits before adopting: (1) any log() override that doesn't call parent::log() needs an explicit if ($this->responseIsFromCache) { return; } unless cache-hit logging is wanted; (2) review exception messages and getExtendedData() for sensitive content now landing in the same entry as the response body; (3) ensure postProcess() rejects only with Throwable — a non-serializable rejection now throws inside the stringify step, aborting the whole log write and masking the real error as the promise's rejection reason; (4) expect the response body to appear twice on transfer-level exceptions and recheck any structural log parsers; (5) the responseFromCache()-based manual-logging pattern still works with no double-write, but overriding log() directly is now the cleaner pattern per the AbstractRequest::log() docblock; (6) tests asserting "nothing logged on parse/postProcess failure" need updating — file count for cache misses is unchanged, but entry content now differs. For plain consumers that only override getLogFolder(), nothing changes.