Ovh Sdk Laravel Package

Product Decisions This Supports

• Build vs. buy for OVHcloud integration: This package owns the transport, auth/signature, and error-taxonomy layer for OVHcloud APIs (DNS zones first). Teams deciding whether to hand-roll a client should weigh that 0.5.0 is still hardening fundamentals — response decoding, time-skew auth, and filter validation — meaning the "buy" option is credible but pre-1.0 and still churning its error contract.
• Retry and resiliency policy design: CouldNotDecodeResponse (non-JSON/empty body, JsonException available via getPrevious()) is now cleanly separable from CouldNotReadResponse (valid JSON, wrong shape). This lets us specify a retry policy that retries only malformed/empty-body responses and fails fast on wrong-shape responses, rather than blanket-retrying all read failures.
• Upgrade scoping for 0.5.0: This is a breaking release for anyone catching JsonException or TypeError from responses. Any service catching those must migrate to CouldNotDecodeResponse / CouldNotReadResponse. Roadmap item: audit and patch catch blocks, add regression tests, ship before we pin the dependency.
• Reliability of scheduled DNS automation: The GET /auth/time fix removes a silent failure mode where a non-integer time was read as 0, producing a wrong cached time delta for an hour and failing the signature of every request. For cron-driven DNS task polling, this converts an hour-long outage class into an immediate, diagnosable exception — a strong argument for adopting the release rather than staying on 0.4.x.
• Feature-level UX for DNS task filtering: tasks()->ids() / tasks()->list() now reject TaskStatus::Problem client-side with CouldNotFilterZoneTasks instead of round-tripping to a 400 Invalid inputs. Product decision: our own UI/API must not offer "Problem" as a task filter option; document that Problem can still appear as a returned status, so read paths need to handle it.
• Support and error-message quality: Empty list routes no longer masquerade as empty lists, and object routes returning lists now say "response is not an object." This reduces false-positive "no work to do" states in DNS automation — directly relevant to any product logic that treats an empty result as success.
• Test strategy input: The live suite now exercises each task status as a filter and asserts OVHcloud still refuses problem. This upstream contract test is a signal we can lean on rather than duplicating, and a hint that OVHcloud's published schema and actual behaviour diverge.

When to Consider This Package

Consider adoption when:

• You are integrating with OVHcloud (DNS zones in particular) from Laravel/PHP and would otherwise build signature/auth handling, request plumbing, and typed error mapping in-house.
• Your automation relies on polling DNS task statuses and you need distinguishable failure classes (transport vs. decode vs. shape vs. invalid filter) to drive retries, alerting, and idempotency.
• You can absorb a pre-1.0 dependency: pin exact versions, review changelogs per release, and own the migration cost of exception-contract changes.
• Your call sites can be updated to catch CouldNotDecodeResponse before CouldNotReadResponse, and you can drop any catch (JsonException) or TypeError reliance on responses.
• You want the client to fail fast on invalid inputs (e.g. problem as a filter) rather than surfacing an opaque BadRequestException from the provider.

Look elsewhere or defer when:

• You need a stable public API with semantic-versioning guarantees; exception types are still moving at 0.5.0.
• You depend on lenient behaviour — specifically, treating an empty body on a list route as an empty list. That is now an exception and will break such assumptions.
• Your architecture requires generic JSON decoding independent of OVHcloud response semantics, or you need providers beyond OVHcloud's surface.
• You cannot tolerate provider-behaviour coupling: the problem filter guard is a workaround for an OVHcloud schema/reality mismatch, so behaviour may need to change again if OVHcloud fixes or re-documents it.
• You want batteries-included caching, rate limiting, or queue orchestration — this package covers transport and errors, not workflow.

How to Pitch It (Stakeholders)

For executives: This release hardens the OVHcloud integration we would otherwise build and maintain ourselves. Its most valuable change is a reliability fix: a server-time parsing bug that could silently break every signed request for up to an hour is now a loud, immediate error. The rest is stricter, more honest error reporting — an empty or malformed response can no longer be mistaken for "nothing to do," which is exactly the kind of false success that causes missed DNS changes in production. Cost is a one-time migration of error-handling code; benefit is fewer silent outages and clearer incident diagnosis.

For engineering: 0.5.0 is a breaking change to the error contract, not a feature drop. Three migrations are required: (1) replace catch (JsonException) on responses with catch (CouldNotDecodeResponse) — the JsonException is still reachable via getPrevious(); (2) replace reliance on TypeError for scalar-where-object/list responses with catch (CouldNotReadResponse); (3) stop passing TaskStatus::Problem to tasks()->ids()/list() — it now throws CouldNotFilterZoneTasks (an InvalidArgumentException) before any HTTP call. Note the asymmetry: Problem is invalid as a filter but still valid as a returned status, so read paths must handle it. Order your catch blocks CouldNotDecodeResponse → CouldNotReadResponse and retry only the former. Also expect an empty body on a list route to throw rather than return [], and object routes returning JSON lists to report a shape error instead of a missing-field error — both will surface latent assumptions in existing tests. The upstream live suite now pins the problem-filter refusal, so we can treat that as an externally verified contract and drop our own duplicate test. Recommendation: adopt 0.5.0, pin the version, and schedule the exception-catch audit as a small, well-scoped task rather than deferring — staying on 0.4.x keeps the auth time-skew failure mode live.