Two Tility Laravel Package

Getting Started

• Start by reading BaseApiClient and the package configuration file. The key setting for most integrations is retries, which controls how failed requests are retried.
• Use 1.0.2 or later. Earlier releases had a retry callback signature mismatch on Laravel 12/13, so configured retries did not actually match connection failures or 429 responses.
• First use case: wrap one third-party HTTP API in a small client class extending BaseApiClient, configure retries for idempotent reads, and call it from a service or job rather than from controllers directly.
• Verify the basics before building on top of it:
  • A successful request returns the expected response.
  • A connection failure is retried according to the retries setting.
  • A 429 response is retried according to the retries setting.
  • The retry count and delay are observable in logs or tests.

Implementation Patterns

• One client per external service. Extend BaseApiClient for each API and keep endpoint methods thin: build the request, call the base client, return a typed result or DTO.
• Configure retries centrally. Put retry counts and backoff settings in package config or a dedicated config file, not scattered across call sites. This makes behavior consistent across jobs, commands, and queued work.
• Retry only safe operations by default. Use configured retries for GET, HEAD, and other idempotent calls. For POST/PATCH/DELETE, require an idempotency key or explicit opt-in before retrying.
• Inject clients through the container. Bind service-specific clients in a service provider so tests can swap them or use Laravel’s HTTP fake facilities.
• Test failure paths explicitly. Add tests for connection exceptions and 429 responses, not just successful 200 responses. On Laravel 12/13, assert that the configured retry count is actually applied.
• Use Laravel HTTP client observability. Listen to HTTP client events or enable request logging in non-production environments when debugging retry behavior. Log the attempt number, status code, and final outcome.
• Keep retry policy close to the API contract. Some APIs return Retry-After on 429; verify whether the package honors it or whether the client should translate it into a delay.
• Pin a minimum version. Require ^1.0.2 in composer.json if retry reliability matters for the integration.
• Prefer queued jobs for retry-heavy workflows. HTTP-level retries handle transient failures; job-level retries handle broader workflow recovery. Use both deliberately rather than relying on one to solve everything.

Gotchas and Tips

• Upgrade to 1.0.2 before trusting retries. In earlier versions on Laravel 12/13, the retry callback used the wrong signature and never matched. The setting may have appeared configured while doing nothing.
• Check callback compatibility after Laravel upgrades. The fixed release addresses Laravel 12/13, but retry callbacks are sensitive to framework signature changes. Re-run failure-path tests when upgrading Laravel.
• Do not assume every failure is retried. The release notes specifically mention connection failures and 429 responses. Confirm whether timeouts, DNS failures, 5xx responses, and other exceptions follow the same path.
• Beware retrying non-idempotent requests. A retried POST can duplicate records or charges. Use idempotency keys or disable retries for unsafe methods.
• Tune retry counts and delays. High retry counts can multiply latency and load during an outage. Pair retries with backoff and a sensible timeout.
• Clear config cache when changing retry settings. Laravel config caching can make local changes appear ineffective.
• Debug by asserting attempts, not just final responses. A request can eventually succeed while still revealing that retries were skipped or applied too many times.
• Watch for masked failures. Retries can hide persistent upstream problems. Log final failures with enough context to distinguish “recovered after retry” from “worked first time.”
• Extension points: override request construction, retry policy, or error mapping in service-specific subclasses rather than modifying package internals. Keep overrides narrow so future package fixes, like the 1.0.2 retry correction, remain easy to adopt.