Nativephp Fetch Laravel Package

Technical Evaluation

Architecture fit NativePHP Fetch sits between a Laravel application and the host platform's native HTTP stack, exposing a fluent, Laravel-HTTP-client-shaped API (Fetch:: facade, requests, retries, downloads, fakes) and dispatching lifecycle events into NativeComponents via #[On]. v1.1.0 strengthens the architectural fit in three ways:

• Fetch Macros introduce a configuration-registry pattern (registered once, typically in a service provider) rather than ad-hoc per-call header/token assembly. This aligns with how Laravel teams already think about Http::macro, Response::macro, and named routes — low conceptual overhead, high reuse.
• Base URLs (Fetch::baseUrl() with relative URLs, query strings, and downloads) codify environment-based endpoint configuration (dev/staging/prod, per-tenant hosts) as a first-class concept instead of string concatenation scattered across call sites.
• Global lifecycle events (FetchRequestStarted, FetchRequestCompleted, FetchRequestFailed) now surface on Laravel's event dispatcher while remaining compatible with #[On] in NativeComponents. This is the most architecturally significant change: it enables cross-cutting concerns — telemetry, audit logging, token refresh, offline queueing, global error toasts — to be implemented once in the Laravel layer rather than duplicated per component. That is a genuine separation-of-concerns improvement for native app codebases where the UI layer and transport layer were previously coupled.

Response helpers (created(), notFound(), unauthorized(), unprocessableEntity(), tooManyRequests(), statusIs()) are cosmetic-to-moderate: they improve readability and reduce magic-number drift, but they don't alter the architecture.

Integration feasibility High, with caveats. The package is opt-in, additive, and explicitly backward compatible — all existing request APIs, #[On] events, retries, downloads, fakes, and native behavior are unchanged. No migration work is strictly required to adopt v1.1.0.

Adoption effort per capability:

• Response helpers / statusIs(): near-zero. Mechanical, safe, can be adopted opportunistically during unrelated edits.
• Base URLs: low effort but requires inventorying existing absolute-URL construction and confirming relative-URL resolution behaves correctly with query parameters and downloads — the two edge cases the release explicitly calls out.
• Fetch Macros: low-to-moderate. Requires deciding where macros are registered (service provider vs. bootstrap), naming conventions, and which configuration is genuinely shared vs. per-endpoint. Risk of over-abstraction if applied indiscriminately.
• Global lifecycle events: moderate. Wiring listeners is trivial; the design question is listener scope and volume. Because these fire on every request, a naive FetchRequestStarted listener doing logging or DB writes becomes a per-request hot path.

Technical risk Overall: low, with three concentrated areas.

1. Event volume and observability cost. Global events fire on every request. Synchronous listeners (DB writes, synchronous HTTP calls, heavy serialization) will add latency to every fetch and can compound under retries. Recommend queued or sampled listeners, and explicit budget on what a listener may do.
2. Secret leakage via macros and base URLs. Macros are the intended home for tokens and auth headers; base URLs encourage a single configured host. Both concentrate credentials in one registration site — good for consistency, bad if that site logs config or if a macro is reused against a tenant/user boundary it wasn't designed for. Needs a review rule: macros must not bake in per-user credentials unless explicitly scoped.
3. Backward compatibility surface. The release claims full compatibility; the risk is behavioral rather than API-level — specifically whether relative-URL resolution with query parameters or downloads changes any resolved path, and whether adding global event dispatch introduces listeners that fire in test/fake() scenarios and surprise existing tests. Validate against the existing test suite, not just the changelog.

Lower-severity: response helper naming collisions with existing internal helpers, and macro registration order affecting override behavior.

Key questions

• Do global lifecycle events fire for requests made through Fetch fakes in tests? If so, existing tests with listeners registered may behave unexpectedly.
• Is FetchRequestFailed dispatched on retry exhaustion only, or on every failed attempt? This determines whether failure listeners can double-count.
• Do macros compose (macro → macro) and how is precedence resolved when a macro and a per-call option set the same header/timeout?
• How does Fetch::baseUrl() interact with absolute URLs passed to the same client — ignored, error, or override?
• Are lifecycle events dispatched synchronously in the request path, and is there a documented cost ceiling for listeners?
• Is download progress/resolution affected by relative URLs, and does base URL apply to download targets?
• What is the deprecation policy for the pre-existing #[On] component-event pattern now that Laravel events are supported — is one canonical?
• Does the package's test-fake surface cover macro-defined config (i.e., can we assert on macro-applied headers)?

Integration Approach

Stack fit Assumes a Laravel + NativePHP application with NativeComponents. Fetch is the native-transport client; v1.1.0 makes it behave more like the Laravel HTTP client teams already know (Http::macro, global events, fluent status helpers), which reduces the learning delta for PHP developers moving into native app work. No new runtime dependencies, no new infrastructure, no schema changes — this is a library-level release, not a platform shift.

Migration path No forced migration. Recommended path is progressive adoption, not a version bump project:

1. Upgrade the dependency and run the existing suite plus a smoke build of the native target to confirm no behavioral drift.
2. Adopt response helpers and statusIs() opportunistically — these are pure readability wins with no design commitment.
3. Introduce Fetch::baseUrl() in one client/service at a time, starting with the least critical integration, and verify query-parameter and download paths explicitly.
4. Extract existing repeated header/token/timeout setup into named macros, one domain at a time, keeping the old call sites working in parallel until each macro is validated.
5. Add global lifecycle listeners last, starting with read-only telemetry, then advancing to token refresh or offline handling once volume behavior is understood.

Compatibility

• Backward compatible per the release; existing request APIs, #[On] component events, retries, downloads, fakes, and native behavior are preserved — so #[On] and Laravel events can coexist, which allows incremental listener migration rather than a flag day.
• Forward-compatible with Laravel's event system, meaning existing queued listeners, telescope-style instrumentation, and log channels apply without custom plumbing.
• Watch items: relative-URL resolution behavior, event dispatch during tests/fakes, and any internal helper names that might collide with the new response helpers. Pin the version and validate against the app's existing HTTP test suite before promoting beyond staging.

Sequencing Phase 1 (low risk, immediate): upgrade + regression validation; adopt statusIs() and response helpers. Phase 2 (low risk, config work): base URLs per environment, audited for query-string and download cases. Phase 3 (moderate): macro extraction with a naming/scoping convention and a credential-handling rule. Phase 4 (moderate, highest leverage): global lifecycle listeners — telemetry and logging first, then auth refresh and failure UX. Phase 5: retire duplicate per-component #[On] handlers where the global listener is now authoritative.

Do not sequence Phase 4 before Phase 2/3 if listeners will depend on the resolved base URL or macro-applied config; ordering avoids rework.

Operational Impact

Maintenance Net positive, with a new artifact to own. Macros and base URLs centralize configuration that was previously duplicated per call site, which reduces the surface area for "one endpoint is missing the auth header" defects and shrinks the blast radius of an API base-URL change to a single line. Response helpers remove magic-number drift. The cost is a new piece of shared infrastructure: the macro registry and base-URL configuration become things that must be reviewed, versioned, and documented, and a bad macro now breaks every consumer at once. Assign a clear owner for the registry and treat changes to it like changes to a shared library.

Support Support surface is roughly unchanged for end users; the release reduces the "why does this one request behave differently" class of tickets by giving failures a single observable hook. Support burden shifts internally: the team must be able to answer "which listeners ran on that request" and "which macro applied that header." That implies documentation of macro names and listener purposes, plus log correlation IDs propagated through the lifecycle events. Expect a short ramp of questions during macro rollout, then a decline.

Scaling Two dimensions:

• Request volume / latency. Global events fire on every request. Synchronous listeners will scale linearly with request count and add fixed per-call overhead; under retries, a single logical operation can emit multiple started/failed events. Mitigate with queued listeners, sampling for high-volume telemetry, and a hard rule against blocking I/O in FetchRequestStarted. Treat the failure listener's event volume as a monitoring metric in its own right.
• Multi-tenancy / multi-environment. Base URLs and macros scale well for environment switching, less well for per-tenant hosts unless macros are parameterized. Verify the pattern supports tenant-scoped base URLs before standardizing; if not, keep tenant resolution in a service layer that calls into Fetch rather than encoding tenants in macros.
• No scaling concerns on storage, compute, or dependency footprint — this is a client-side library change.

Failure modes

• Listener-induced latency or failure. A throwing or slow global listener can degrade or break every request. Listeners should be isolated, non-throwing, and non-blocking; consider wrapping in a guard.
• Event double-counting. If FetchRequestFailed fires per attempt rather than per exhausted request, alerting and retry dashboards will over-report. Confirm semantics before building SLOs on it.
• Macro misconfiguration blast radius. A wrong token, stale timeout, or bad header in a macro breaks all consumers simultaneously — a single-point-of-failure that didn't exist when config was per-call. Mitigate with a startup smoke request per macro or a health check.
• Relative-URL resolution edge cases. Query parameters and download paths are the two explicitly called-out cases; a mis-resolved download URL fails silently-ish (bad file or 404 after a delay) rather than loudly. Add explicit tests for both.
• Test/production divergence. If lifecycle events fire under Fetch fakes, tests may pass while listener behavior in production differs, or event assertions may become brittle. Validate the fake/event interaction early.
• Mixed event paradigms. With #[On] and Laravel events both supported, duplicate handling is a realistic near-term failure mode — the same request producing two telemetry records or two toasts. Track which handlers have migrated.
• Silent compatibility regressions. "Backward compatible" is a claim to verify, not assume; a native build smoke test per release is the cheapest guard.

Ramp-up Low for individual contributors: the helpers and statusIs() are self-documenting, and macros mirror the Http::macro idiom most Laravel developers already know. The steeper curve is for whoever owns the shared layer — deciding macro boundaries, base-URL strategy, and listener design — and for on-call, who need a mental model of the request lifecycle to diagnose failures now that behavior is spread across listeners rather than colocated in components. Budget roughly a short onboarding session plus written conventions for the macro registry and event listeners; that documentation is the main enablement deliverable of this upgrade, not the code changes themselves. Overall ramp-up cost is modest and front-loaded, and the consolidation this release enables should reduce long-term cognitive load in native component code.