Z Api Php Sdk Laravel Package

Technical Evaluation

Architecture fit: saade/z-api-php-sdk is a thin Laravel service-provider wrapper around the Z-API (WhatsApp Business messaging) HTTP API, built on the Saloon HTTP client. It slots into the standard Laravel package pattern: composer install, config publish, credential env vars, and a facade/injected client. There is no persistence layer, no queueing, no domain model — it is a transport adapter. That makes it a low-coupling dependency that is easy to isolate behind our own WhatsAppGateway interface.

Integration feasibility: Straightforward for a greenfield Laravel service. The two material constraints in v1.1.0 are (a) Saloon 4 is now a hard requirement, and (b) Laravel 13 support is newly added. Any application that pins Saloon 3 directly, or that depends on another package requiring Saloon 3, will hit a Composer conflict. This is resolvable but must be checked before we commit.

Technical risk:

• Dependency-major bump (medium-high): Moving from Saloon 3 to 4 is the dominant risk. If we only consume this SDK and never touch Saloon directly, the blast radius is small — Composer resolves, the SDK's internal calls are already adapted. If we use Saloon for other integrations, we inherit Saloon 4's breaking changes across all of them.
• CVE remediation (positive, but verify): The release explicitly pulls in Saloon 4 to address CVE-2026-33942, CVE-2026-33182 and CVE-2026-33183. We should confirm severity and whether our current Saloon 3 version is actually exposed (e.g., is the vulnerable code path reachable given how the SDK constructs requests). This is likely the strongest argument for taking the upgrade.
• Laravel 13 support (low): Additive; no indication older Laravel versions were dropped. Confirm the package's composer.json constraint range rather than trusting the changelog headline.
• Maintainer/bus factor (medium): Single-maintainer package. Release activity is largely Dependabot-driven, which is a signal of automation, not of deep feature investment. Acceptable for a thin adapter; not acceptable as a strategic dependency without a fallback.
• Governance: No breaking-change notices, no deprecations, no API surface changes are disclosed. Semver minor bump is consistent with the changelog.

Key questions to close before approval:

1. Does composer why saloon/saloon show Saloon as a direct or transitive dependency anywhere else in our stack, and at what version?
2. Are the three CVEs reachable in our usage, and what is the remediation SLA driving this?
3. Does Saloon 4 change anything we use directly — retry middleware, request/response hooks, mocking in tests, or custom authenticators?
4. What Laravel versions does the package's composer.json actually constrain to? Does it still support our current LTS, or does taking v1.1.0 force a Laravel 13 upgrade we have not scheduled?
5. Does the SDK cover the Z-API endpoints we need (text, media, templates, webhooks), and how are webhook payloads validated?
6. What is our fallback if this package is abandoned — how much of our code touches the SDK directly versus our own gateway abstraction?

Integration Approach

Stack fit: The package is a natural fit if we are on a modern Laravel baseline and have already standardized on Saloon (or are willing to). Its scope is narrow enough that wrapping it in an internal adapter costs little and buys real exit optionality. I would not let SDK request classes leak into domain or application layers.

Migration path (v1.0.0 → v1.1.0):

1. Audit: composer why saloon/saloon, composer show saloon/saloon, and a grep for direct Saloon imports in our codebase.
2. If Saloon is SDK-only: bump in a branch, run the full suite, and diff the lockfile to confirm nothing unexpected moves.
3. If Saloon is also used directly: treat this as a Saloon 3→4 application migration, not a package bump. Scope that separately and sequence it first, then take the SDK.
4. Verify credentials, base URL config, and webhook signature handling in a Z-API sandbox before promoting.

Compatibility: Primary compatibility axes are PHP version, Laravel version range, and Saloon major. All three are hard constraints in composer.json; read it directly rather than relying on the changelog. Also confirm Guzzle major version alignment, since Saloon sits on top of it and conflicts surface there.

Sequencing:

• Phase 1 (now, ~1 sprint): CVE applicability assessment and Saloon dependency audit. This determines whether the upgrade is urgent or routine.
• Phase 2: Saloon 4 migration in a branch with full regression, including integration tests against a Z-API sandbox.
• Phase 3: Staging canary with real message traffic on a low-volume number; observe error rates for one to two weeks.
• Phase 4: Production rollout behind the gateway abstraction, so a rollback is a config/composer revert rather than a code change.
• Phase 5 (independent): Laravel 13 upgrade, scheduled on its own merits — do not couple it to the security fix.

Operational Impact

Maintenance: Low surface area, but single-maintainer risk. Pin to a minor version range, subscribe to GitHub releases, and keep an internal note on what a fork would cost. The presence of Dependabot and Laravel Pint workflows suggests basic hygiene; the absence of substantive feature work suggests limited roadmap.

Support: Community-only, GitHub-issues based. No vendor SLA. We should own the runbook for Z-API authentication, token rotation, and webhook re-registration — those are operational concerns the SDK will not cover.

Scaling: The SDK itself is stateless and adds negligible overhead. Real scaling levers are Z-API rate limits, WhatsApp template approval throughput, and our own queueing. Outbound sends should go through queued jobs with per-tenant throttling and idempotency keys; inbound webhooks need to be acknowledged fast and processed asynchronously. Neither concern is addressed by this package, so we build it.

Failure modes to instrument:

• Saloon 4 incompatibility presenting as runtime Error/TypeError on first send after deploy — caught by staging canary.
• Z-API auth token expiry or revocation producing 401s that look like application errors.
• Rate-limit 429s during campaigns; requires backoff and queue-depth alerting.
• Webhook delivery gaps (Z-API retries, our endpoint 5xx) leading to silently missed inbound messages — needs a reconciliation job and dead-letter path.
• Silent partial failures: message accepted by Z-API but not delivered (invalid number, template rejected). Persist provider message IDs and status callbacks.

Ramp-up: Low. A Laravel developer familiar with HTTP clients can be productive in one to two days; the Saloon 4 migration adds a few days of dependency archaeology. Budget roughly one engineer-week end-to-end for a careful upgrade including CVE validation and staging soak, assuming Saloon is SDK-only. If Saloon is used directly elsewhere, double it.