Zammad Api Client Php Laravel Package

Technical Evaluation

Architecture fit

• Framework-agnostic PHP SDK, not a Laravel package. No service provider, facade, config publishing, queue or event integration. It slots in as an SDK layer beneath our domain code, not as a Laravel-native connector.
• Maintained under the Zammad org itself. First-party stewardship is the strongest signal here and outweighs the 64 stars / 0 dependents, which reflect PHP-ecosystem discoverability rather than code quality.
• v2 surface is Client → resource(ResourceType::X) → get/all/search/save/delete/add/remove/import. Covers tickets, articles, states, priorities, groups, users, organizations, tags, links, text modules, and CSV import. Resource objects are stateful and single-use (get cannot be re-called on a populated object), which pushes a per-operation object lifecycle into our calling code.
• No schema awareness: the README explicitly states the client does not validate or know resource fields, and invalid fields are "ignored or return an error." Field validation and domain invariants become our responsibility.

Integration feasibility

• Composer-only install; v2 requires PHP 7.2+, v3 requires PHP 8.1+. No framework conflicts, no native extensions, low install risk.
• v3 RC is the strategically relevant target: typed DTOs, typed exceptions, and a PSR-18 HTTP client. PSR-18 is the real unlock — we can inject Laravel's HTTP client via an adapter so the SDK inherits our logging, tracing, and retry middleware instead of shipping its own Guzzle config.

Technical risk

• Error model in v2 is the largest architectural hazard: failures return the caller Resource object rather than throwing. search()/all() return either an array or the object, forcing !is_array() checks at every call site. A missed check converts an outage into "zero results." v3's typed exceptions fix this; that alone justifies targeting v3 or wrapping v2 aggressively.
• License is NOASSERTION. Zammad is AGPL; a derivative client is plausibly AGPL too. Legal review is a hard gate before embedding in a commercial or SaaS product.
• Release metadata (2026-10-02) looks anomalous and should be verified against Packagist before pinning.
• No retry, backoff, or rate-limit handling. Synchronous only. No webhook or event ingestion — inbound change detection is polling-only unless we wire Zammad webhooks ourselves.

Key questions

• What is the actual license, and are AGPL obligations acceptable given our distribution model?
• What is the v3 GA date, and can we ship on RC with a supported fallback?
• Which Zammad version runs in our environment, and is its pagination cap compatible with our sync volume?
• Can we authenticate with http_token instead of storing user passwords? Is on-behalf-of permitted by our Zammad role model?
• Do we own the Zammad instance or is it vendor-hosted (affects rate limits, version pinning, and webhook configuration)?

Integration Approach

Stack fit

• v2 fits Laravel 9/10 on PHP 7.2+; v3 fits Laravel 10/11 on PHP 8.1+. Not a blocker, but v3's PHP floor drops PHP 8.0 and Laravel 9.
• Wrap, don't scatter: a config/zammad.php (url, token, timeout, verify, default group/state), a ZammadServiceProvider binding Client as a singleton, and a single ZammadGateway class that is the only file importing ZammadAPIClient\*. Domain code depends on our interface and DTOs.
• On v3, bind a PSR-18 adapter over Laravel's HTTP client so there is one HTTP stack, one set of retry rules, and one trace context.

Migration path

• Greenfield: spike on v3 RC; fall back to ^2.3 only if the RC blocks delivery.
• Existing v2 usage: follow the published v3 migration guide. The breaking surface is the error model and typed DTOs — both contained if the SDK is behind the gateway, making migration a one-file change.

Compatibility watchpoints

• Zammad 3.4.1+ is nominally supported, but field shapes drift across Zammad versions. Pin and test against our actual instance, not the docs.
• v2's sticky setOnBehalfOfUser() persists on the Client instance; singleton binding plus queue workers means header leakage across jobs unless reset in a finally.

Sequencing

1. License and legal clearance — hard gate.
2. Spike: auth, fetch ticket + articles + one attachment, one write.
3. Config + provider + gateway with errors translated into Laravel exceptions.
4. Read path: queued cursor-based sync into local mirror tables (keyed on updated_at).
5. Write path: create/reply/update, tags, links — all behind jobs with idempotency keys.
6. Inbound: Zammad webhook → Laravel route → job, retiring polling.
7. Pagination/load test against real server-side caps.
8. Cutover with dual-run validation.

Operational Impact

Maintenance

• Small code footprint, but the wrapper is ours to own forever. Track v3 RC→GA and budget a spike per upstream minor. First-party maintenance materially lowers abandonment risk versus a comparable community package.

Support

• GitHub issues only, no SLA, thin community (0 dependents) means few answers to borrow. The package deliberately defers field-level knowledge to Zammad's REST docs, so the team must be fluent in Zammad's domain model — groups, roles, states, priorities, article types — not just PHP.

Scaling

• Every operation is a blocking HTTP round trip; default timeout 5s, no retry/backoff. Ticket → articles → attachments is a textbook N+1 (1 + N + M requests per ticket).
• Server-side pagination caps silently truncate search()/all(). Any "sync everything" loop must page until a short page is returned, or it will quietly under-sync.
• Never call the client inline in a request path. All writes go through rate-limited queues; all reads through scheduled sync jobs.

Failure modes to design for

• v2 error-as-return-value degrades to empty results instead of loud failure.
• Partial writes: ticket created, tag add fails, state orphaned — needs compensating logic or idempotent replay.
• Credential and OAuth2 token expiry with no refresh handling in the client.
• Sticky on-behalf-of header leaking across jobs in a shared singleton.
• Unbounded attachment downloads exhausting memory.
• 429/5xx from Zammad with no client-side retry, surfacing as lost work.

Ramp-up

• Roughly 2–4 days for one engineer to a working read path; 1–2 weeks for a resilient bidirectional sync with webhooks, idempotency, and observability. The genuine unknowns are license clearance and v3 GA timing — not the code.