Getting Started

Install with composer require <vendor>/<package> and let Laravel auto-discover the service provider.
Publish the config (php artisan vendor:publish --tag=...) and set credentials/endpoints in .env; avoid committing tokens.
First place to look: the package config file for HTTP options (retry_delay_ms, retry_multiplier, timeouts) and FinamClient for request/response behavior.
Resolve the client from the container rather than instantiating it directly, so config and HTTP client customizations apply consistently.
First use case: make one authenticated read-only call (e.g. account or market data) from a tinker session or a simple artisan command, then inspect logs to confirm retry/timeout settings behave as expected.

Implementation Patterns

Inject the client, don’t new it up. Type-hint FinamClient (or the package’s binding/interface) in controllers, jobs, and services so Laravel wires config and the underlying HTTP client.
Tune retries per environment. Keep retry_multiplier = 1.0 for fixed delays in local/dev, and raise it (e.g. 1.5–2.0) in production where 429/503 responses benefit from exponential backoff.
Respect Retry-After. v1.2.0 honors the header when present; still set a sane retry_delay_ms as the fallback for responses without it.
Wrap calls in your own domain service. Keep retry/backoff policy in config, but map transport failures and HTTP errors to domain exceptions so controllers and jobs don’t depend on Guzzle details.
Use queued jobs for write operations. Combine the package’s HTTP retries with Laravel job tries/backoff, and make operations idempotent where the upstream API allows it.
Test with Http::fake(). Assert request counts and sequences for 429 → 200 and 503 → 200 flows, including a Retry-After header, to lock in the new behavior.
Log retries at warning level. Emit structured context (endpoint, status, attempt, delay) so transient upstream issues are visible without noisy stack traces.

Backward-compatible default can surprise you. retry_multiplier defaults to 1.0, which means fixed delays. If you expected exponential backoff from the release notes, you must opt in explicitly.
Retries are not infinite. Confirm the package’s max-attempt setting and total worst-case delay; combined with Retry-After, sleep time can exceed queue worker or HTTP timeout limits.
Retry-After parsing matters. The header may be seconds or an HTTP date; verify behavior in tests and avoid assuming it is always numeric.
Don’t blindly retry non-idempotent requests. A retried POST can duplicate side effects upstream; gate retries or use idempotency keys where supported.
Config caching hides changes. After editing retry settings, run php artisan config:clear (or rebuild the cache) before debugging.
Debugging retries: check Laravel logs and the underlying HTTP client’s request/response events; temporarily lower attempts or raise delay to observe behavior without hammering the API.
Extension point: if the package exposes the underlying HTTP client or Guzzle options, prefer middleware/handlers there for cross-cutting concerns (auth refresh, tracing) instead of wrapping every call site.
Quality signal: the release keeps PHPUnit (107 tests), PHPStan, and Psalm green, so static analysis and test fakes are reasonable guardrails when you customize retry behavior.