EEPIC-#79 - v3 refactor: PSR-compliant client with typed DTOs, reposi…

[derpixler]

EEPIC-#79 — v3: PSR-compliant PHP client with typed DTOs, repositories, and enums

Breaking Changes (v2 → v3)

Architecture

v2	v3
Client (arrays, magic strings)	ZammadClient with typed factory methods
Resource + ResourceType enums	Repository pattern + typed DTOs
$ticket->getValue('title')	$ticket->title (typed property, IDE autocomplete)
$ticket->hasError() / $ticket->getError()	Typed exceptions (NotFoundException, etc.)
new Client(['url' => ..., 'http_token' => ...])	ZammadClient::withToken($url, $token)
PHP >= 7.2	PHP >= 8.1

Files removed (~3,900 LOC)

• src/Client.php, src/HTTPClient.php, src/HTTPClientInterface.php
• src/Resource/ — all 10 resource classes (AbstractResource, Ticket, User, etc.)
• src/ResourceType.php
• src/Exception/ — old exception classes
• test/ZammadAPIClient/ — old test suite

What's new (~10,200 LOC)

Core layer (src/Core/)

• ZammadClient — entry point with withToken(), withOAuth2(), withBasicAuth(),
  withClient(). Auto-normalizes URL (appends /api/v1). Memoized repositories via repo().
  Impersonation via performOnBehalfOf() / setOnBehalfOfUser().
• RequestHandler — PSR-18 HTTP transport with JSON (de)serialization, HTTP status→exception
  mapping, X-On-Behalf-Of header support, configurable retries.
• RetryAfterMiddleware — PSR-18 decorator: auto-retries on HTTP 429 with Respect-Retry-After
  header parsing (RFC 7231 HTTP-date + delta-seconds).
• AbstractRepository — generic CRUD with generator-based cursor pagination, explicit page
  methods, resource()/list() Ruby-style accessors, extractItems().
• PaginatedList — ArrayAccess + IteratorAggregate with page(), pageNext(), pagePrev(),
  each(), totalCount(), allPages().
• Resource — mutable stateful wrapper with property-level change tracking.
  save() sends only changed fields; destroy() sends DELETE.
• DtoHydrator — reflection-based hydration: maps API array keys to constructor parameters
  with type-driven coercion via Cast.
• Cast — safe scalar coercions: dateTime(), string(), intOrNull(), boolOrNull().
• ConnectionConfig — immutable config DTO (verifySsl, timeout, maxRetries, logger).
• RepositoryRegistry — single source of truth mapping 10 repositories to API paths and DTOs.
• ResponseParser — extracts resource arrays from Zammad's {tickets: [...], assets: {...}} wrapper.
• HttpPageFetcher — PSR-18 page fetcher for PaginatedList.
• Traits: HasTimestamps, HydratesFromArray, SerializesToArray.

Contracts (src/Core/Contracts/)

• RepositoryInterface — find, all, search, create, update, patch, delete
• DTOInterface — fromArray(), toArray(), id()
• DeletableInterface — delete($id)
• PatchableInterface — toPatchArray()
• RequestHandlerInterface, ClientInterface, PageFetcherInterface

Endpoints — 10 repositories + typed DTOs (src/Endpoints/)

• Tickets: TicketRepository (CRUD + delete + getTicketArticles),
  TicketDTO (14 fields), TicketUpdateDTO (partial update, 8 fields)
• Users: UserRepository (CRUD + delete + CSV import), UserDTO (13 fields)
• Organizations: OrganizationRepository (CRUD + delete + CSV import), OrganizationDTO
• Groups: GroupRepository (CRUD + delete), GroupDTO
• TicketArticles: TicketArticleRepository (getForTicket, getAttachmentContent),
  TicketArticleDTO (25 fields), TicketArticleType enum (Note, Email, Phone, Sms, Web)
• TicketStates: TicketStateRepository, TicketStateDTO
• TicketPriorities: TicketPriorityRepository, TicketPriorityDTO
• Tags: TagRepository (add, remove, tagSearch), TagDTO
• TextModules: TextModuleRepository (CRUD + delete + CSV import), TextModuleDTO
• Links: LinkRepository (add, remove, list), LinkDTO

Exceptions (src/Exceptions/) — typed hierarchy

• AuthenticationException (401), ForbiddenException (403), NotFoundException (404)
• ValidationException (422, with $errors array per-field)
• RateLimitException (429, with $retryAfterSeconds, auto-retried)
• ServerErrorException (5xx), NetworkException (DNS, timeout, connection refused)

Bridge (src/Bridge/)

• LaravelServiceProvider — auto-registers ZammadClient as singleton
• SymfonyBundle — Symfony DI integration

Tests — 227 unit tests, 12 integration test classes

• Unit: AbstractRepository, Cast, DtoHydrator, PaginatedList, RequestHandler, Resource,
  RepositoryRegistry, RetryAfterMiddleware, all DTOs, all repositories, ZammadClient
• Integration: Tickets, Users, Groups, Organizations, Tags, Links, TicketArticles,
  Pagination, Search, ErrorHandling, ReferenceData, User cleanup

Documentation

• docs/migration-v3.md — step-by-step v2→v3 migration guide
• docs/migration-v3-examples.md — 15 side-by-side before/after code examples
• docs/v2-reference.md — preserved v2 documentation
• docs/alternative-clients.md — non-Guzzle transport setup
• examples/cookbook.php — 9 runnable v3 recipes
• README.md — rewritten with DTO field tables, update method decision guide,
  error handling table (HTTP→exception mapping + auto-retry), paradigm guide

CI

• New GitHub Actions workflow: PSR-12 lint, PHPStan level=max, 227 unit tests,
  integration tests against live Zammad instance