Zammad API Client v3 — Modernization

[derpixler]

Overview & Goal

The goal of this epic is to modernize the Zammad PHP API Client. The current v2 client suffers from tight coupling to Guzzle, a monolithic architecture, and a reliance on associative arrays, which lacks type safety and IDE support.

Primary Goal: Migrate from a Guzzle-coupled, array-based client to a PSR-compliant, type-safe library with a modern developer experience.

Critical Success Criterion: Backward compatibility. Existing v2 integrations must continue to work without code changes in v3. Legacy support is handled via the v2.2.2 tag — no active development is required for the legacy layer.

---

Architectural Principles

• PSR-First: Utilization of PSR-18 (HTTP), PSR-17 (Factory), and PSR-3 (Log) without framework dependencies in the core.
• Separation of Concerns: Clear layering (RequestHandler → Repository → DTO).
• Type Safety: Use of readonly DTOs and strict PHP typing.
• Testability: Support for unit tests (using mocks) and integration tests (against a live Zammad instance).
• DI-First: All dependencies must be injectable; no new keywords inside constructors.
• Lean: Minimal dependencies, no policy classes, and no framework bloat.

---

Key Deliverables

1. PSR-18 RequestHandler (S2): An swappable HTTP layer with automated exception mapping (e.g., for 429/Rate-Limit or 404/NotFound).
2. Typed DTOs (S3): Full type definitions for all resources (Ticket, User, etc.) to enable IDE autocomplete.
3. Generator-based Repositories (S4): Implementation of AbstractRepository for efficient pagination using IteratorAggregate.
4. Resilience (S2/S4): Integrated RetryAfterMiddleware (PSR-18 decorator) for automatic handling of HTTP 429 responses.

---

How to Pick Up an Issue

1. Check the GitHub issue — verify dependencies are resolved and no conflicting in-progress work exists.
2. Read the Acceptance criteria in the issue — these are your test-first checklist.
3. Write the test FIRST (RED), then implement (GREEN).
4. Run: vendor/bin/phpunit --testsuite=unit --filter=YourTestName.
5. Run: vendor/bin/phpcs --standard=PSR12 src/ — 0 errors required.
6. Mark the GitHub issue as ✓ Done.