From d96405f8507fb503e1a481b1e7205d6862bce429 Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 01/10] feat(S2): Add UserDTO with typed fields (login, email,
 roles, active, etc.) and lenient fromArray parsing

EPIC-#79

#93
---
 src/Endpoints/Users/UserDTO.php | 49 +++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 src/Endpoints/Users/UserDTO.php

diff --git a/src/Endpoints/Users/UserDTO.php b/src/Endpoints/Users/UserDTO.php
new file mode 100644
index 0000000..a713c28
--- /dev/null
+++ b/src/Endpoints/Users/UserDTO.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Users;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad user resource (`/api/v1/users`).
+ *
+ * Users encompass both agents (Zammad staff) and customers (end-users). The
+ * distinction is made by the `role_id` field: agents have the "Agent" role,
+ * customers have the "Customer" role.
+ *
+ * Key fields:
+ *  - `login`           — Unique username; required for agents, optional for customers.
+ *  - `email`           — Primary email address; used for notifications and authentication.
+ *  - `firstname`/`lastname` — Display name components.
+ *  - `organization_id` — Links the user to an organization (customers only, typically).
+ *  - `role_id`         — Determines whether the user is an agent or a customer.
+ *
+ * All fields are nullable because the minimum required fields for creation
+ * differ between agents (need `login`) and customers (need `email`), and
+ * partial construction is common when building a DTO just to update one field.
+ */
+final readonly class UserDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public ?string $login = null,
+        public ?string $email = null,
+        public ?string $firstname = null,
+        public ?string $lastname = null,
+        public ?string $phone = null,
+        public ?int $organization_id = null,
+        public ?int $role_id = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 35ca3232ccac75dbd375cc27af39643e5ea599a6 Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 02/10] feat(S2): Add OrganizationDTO with typed fields (name,
 domain, members, note, etc.)

EPIC-#79

#94
---
 .../Organizations/OrganizationDTO.php         | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 src/Endpoints/Organizations/OrganizationDTO.php

diff --git a/src/Endpoints/Organizations/OrganizationDTO.php b/src/Endpoints/Organizations/OrganizationDTO.php
new file mode 100644
index 0000000..bcdc107
--- /dev/null
+++ b/src/Endpoints/Organizations/OrganizationDTO.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Organizations;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad organization resource (`/api/v1/organizations`).
+ *
+ * Organizations group customer users under a shared company entity. A customer
+ * can belong to one primary organization; agents and organizations are separate
+ * (agents typically have no organization). Tickets created by a customer inherit
+ * the customer's organization, enabling company-wide ticket views.
+ *
+ * Server-assigned fields (`id`, `created_at`, `updated_at`) default to null and
+ * are populated by the API after `create()` or `find()`.
+ */
+final readonly class OrganizationDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 1aa0fd15964b8546c53cc9d57ab79579b898c9ad Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 03/10] feat(S2): Add GroupDTO with typed fields (name,
 signature_id, email_address_id, follow_up_*, active, etc.)

EPIC-#79

#95
---
 src/Endpoints/Groups/GroupDTO.php | 37 +++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 src/Endpoints/Groups/GroupDTO.php

diff --git a/src/Endpoints/Groups/GroupDTO.php b/src/Endpoints/Groups/GroupDTO.php
new file mode 100644
index 0000000..e231e0b
--- /dev/null
+++ b/src/Endpoints/Groups/GroupDTO.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Groups;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad group resource (`/api/v1/groups`).
+ *
+ * Groups are routing containers for tickets. Every ticket belongs to exactly one
+ * group, which determines which agents can see and work on it. Groups also control
+ * SLA assignments, notification rules, and signature selection.
+ *
+ * Server-assigned fields (`id`, `created_at`, `updated_at`) default to null so
+ * the DTO can be constructed before persisting. After a `create()` or `find()` call
+ * the returned DTO will have these fields populated by the server.
+ */
+final readonly class GroupDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 232885a13337ae12977a2e31f2153dac334e94ee Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 04/10] feat(S2): Add TicketArticleDTO with typed fields
 (ticket_id, type, sender, subject, body, content_type, etc.)

EPIC-#79

#96
---
 .../TicketArticles/TicketArticleDTO.php       | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 src/Endpoints/TicketArticles/TicketArticleDTO.php

diff --git a/src/Endpoints/TicketArticles/TicketArticleDTO.php b/src/Endpoints/TicketArticles/TicketArticleDTO.php
new file mode 100644
index 0000000..e64b73b
--- /dev/null
+++ b/src/Endpoints/TicketArticles/TicketArticleDTO.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TicketArticles;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad ticket article resource (`/api/v1/ticket_articles`).
+ *
+ * A ticket article is a single message within a ticket's communication thread.
+ * It can represent an inbound email, an outbound reply, an internal note,
+ * a phone call log, or any other communication channel Zammad supports.
+ *
+ * Key fields:
+ *  - `ticket_id`    — The parent ticket this article belongs to.
+ *  - `type`         — Channel/type string (e.g. `'email'`, `'note'`, `'phone'`).
+ *  - `body`         — The content of the message.
+ *  - `content_type` — MIME type of the body (`'text/plain'` or `'text/html'`).
+ *
+ * Attachments are not represented as fields on the DTO; they must be downloaded
+ * separately via {@see \ZammadAPIClient\Endpoints\TicketArticles\TicketArticleRepository::getAttachmentContent()}.
+ *
+ * All fields are nullable because this DTO is also used for partial construction
+ * when creating new articles (not all fields are required by the API).
+ */
+final readonly class TicketArticleDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public ?int $ticket_id = null,
+        public ?string $type = null,
+        public ?string $body = null,
+        public ?string $content_type = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From dbaa93271a6d1fe006be842e6eb2b6e57fb9925c Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 05/10] feat(S2): Add TicketStateDTO with typed fields (name,
 state_type_id, active, note, etc.)

EPIC-#79

#97
---
 src/Endpoints/TicketStates/TicketStateDTO.php | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 src/Endpoints/TicketStates/TicketStateDTO.php

diff --git a/src/Endpoints/TicketStates/TicketStateDTO.php b/src/Endpoints/TicketStates/TicketStateDTO.php
new file mode 100644
index 0000000..52c0ded
--- /dev/null
+++ b/src/Endpoints/TicketStates/TicketStateDTO.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TicketStates;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad ticket state resource (`/api/v1/ticket_states`).
+ *
+ * Ticket states describe the current lifecycle stage of a ticket (e.g. "new",
+ * "open", "pending reminder", "closed"). Each state belongs to a state type
+ * (via `state_type_id`) that controls Zammad's internal behaviour, such as
+ * whether a ticket counts as open or closed for SLA calculations.
+ *
+ * Key fields:
+ *  - `name`          — Display label (e.g. `'open'`).
+ *  - `state_type_id` — References the internal state type; determines Zammad's
+ *                      automation behaviour for this state.
+ *
+ * Typically retrieved with `all()` to populate a state selector dropdown;
+ * rarely created or modified via the API.
+ */
+final readonly class TicketStateDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?int $state_type_id = null,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From da89ccf11b026e4c82e2cc799ac60fe79a51e862 Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 06/10] feat(S2): Add TicketPriorityDTO with typed fields
 (name, default_create, ui_icon, ui_color, active, etc.)

EPIC-#79

#98
---
 .../TicketPriorities/TicketPriorityDTO.php    | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 src/Endpoints/TicketPriorities/TicketPriorityDTO.php

diff --git a/src/Endpoints/TicketPriorities/TicketPriorityDTO.php b/src/Endpoints/TicketPriorities/TicketPriorityDTO.php
new file mode 100644
index 0000000..b993900
--- /dev/null
+++ b/src/Endpoints/TicketPriorities/TicketPriorityDTO.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TicketPriorities;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad ticket priority resource (`/api/v1/ticket_priorities`).
+ *
+ * Ticket priorities classify the urgency level of a ticket (e.g. "1 low",
+ * "2 normal", "3 high"). The default Zammad installation ships with three
+ * priorities; administrators can create additional ones via the API or UI.
+ *
+ * The `name` field is the display label; Zammad uses the numeric `id` when
+ * assigning a priority to a ticket via the `priority_id` field on
+ * {@see \ZammadAPIClient\Endpoints\Tickets\TicketDTO}.
+ */
+final readonly class TicketPriorityDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 464f1485f8fae93d102b3c29431d3f6163ff902c Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 07/10] feat(S2): Add TagDTO with typed fields (name, count,
 etc.)

EPIC-#79

#99
---
 src/Endpoints/Tags/TagDTO.php | 42 +++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 src/Endpoints/Tags/TagDTO.php

diff --git a/src/Endpoints/Tags/TagDTO.php b/src/Endpoints/Tags/TagDTO.php
new file mode 100644
index 0000000..3ec5222
--- /dev/null
+++ b/src/Endpoints/Tags/TagDTO.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\Tags;
+
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a single tag assignment on a Zammad object (`/api/v1/tags`).
+ *
+ * Tags in Zammad are not global labels by themselves; they exist as associations
+ * between a tag name (`value`) and a specific taggable object (identified by
+ * its type name `object` and numeric ID `o_id`).
+ *
+ * Field semantics:
+ *  - `value`  — The human-readable tag string (e.g. `'bug'`, `'urgent'`).
+ *  - `object` — Zammad object class name that the tag is attached to (e.g. `'Ticket'`).
+ *  - `o_id`   — The numeric ID of the specific object instance being tagged.
+ *
+ * All fields are nullable because the `/tag_search` autocomplete endpoint returns
+ * only `id` and `value` without `object` or `o_id`.
+ *
+ * Note: The `id` field here is the tag-assignment ID, not the tag label's ID in
+ * the Zammad tag list. Two identical tag strings on different tickets have
+ * different assignment IDs.
+ */
+final readonly class TagDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public ?int $id,
+        public ?string $object,
+        public ?int $o_id,
+        public ?string $value,
+    ) {
+    }
+}

From 6f7e0bc5a53eddef55d689b596a6e23a196292be Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 08/10] feat(S2): Add TextModuleDTO with typed fields (name,
 keywords, content, active, etc.)

EPIC-#79

#100
---
 src/Endpoints/TextModules/TextModuleDTO.php | 45 +++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 src/Endpoints/TextModules/TextModuleDTO.php

diff --git a/src/Endpoints/TextModules/TextModuleDTO.php b/src/Endpoints/TextModules/TextModuleDTO.php
new file mode 100644
index 0000000..86f4c0b
--- /dev/null
+++ b/src/Endpoints/TextModules/TextModuleDTO.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Endpoints\TextModules;
+
+use DateTimeImmutable;
+use ZammadAPIClient\Core\Contracts\DTOInterface;
+use ZammadAPIClient\Core\Traits\HydratesFromArray;
+use ZammadAPIClient\Core\Traits\SerializesToArray;
+
+/**
+ * Represents a Zammad text module resource (`/api/v1/text_modules`).
+ *
+ * Text modules are canned-response templates that agents can search and insert
+ * into ticket replies. They support Zammad's variable interpolation syntax
+ * (e.g. `#{ticket.title}`, `#{customer.firstname}`) so content is personalised
+ * at insertion time.
+ *
+ * Key fields:
+ *  - `name`     — Display name shown in the search result list.
+ *  - `keywords` — Space-separated keywords that improve searchability without
+ *                 appearing in the inserted text.
+ *  - `content`  — The template body, optionally containing `#{...}` variables.
+ *
+ * Server-assigned fields (`id`, `created_at`, `updated_at`) default to null
+ * and are populated by the API after `create()` or `find()`.
+ */
+final readonly class TextModuleDTO implements DTOInterface
+{
+    use HydratesFromArray;
+    use SerializesToArray;
+
+    public function __construct(
+        public string $name,
+        public ?string $keywords = null,
+        public ?string $content = null,
+        public ?string $note = null,
+        public ?bool $active = null,
+        public ?int $id = null,
+        public ?DateTimeImmutable $created_at = null,
+        public ?DateTimeImmutable $updated_at = null,
+    ) {
+    }
+}

From 55b71d2c86f8b6f49322aef64cfa2fc2f034fa2b Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:06:11 +0200
Subject: [PATCH 09/10] =?UTF-8?q?feat(S2):=20Complete=20typed=20DTOs=20for?=
 =?UTF-8?q?=20all=209=20resources=20=E2=80=94=20Ticket,=20User,=20Organiza?=
 =?UTF-8?q?tion,=20Group,=20TicketArticle,=20TicketState,=20TicketPriority?=
 =?UTF-8?q?,=20Tag,=20TextModule=20+=20TicketUpdateDTO?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EPIC-#79

#81

From 02fd1cf715f55d3fafe20edf55b4e2a8c96160e6 Mon Sep 17 00:00:00 2001
From: Rene Reimann <rr@zammad.com>
Date: Mon, 13 Jul 2026 18:12:44 +0200
Subject: [PATCH 10/10] feat(S2): Add DTOInterface, reflection-based
 DtoHydrator, and HydratesFromArray/SerializesToArray traits

EPIC-#79

#91
---
 src/Core/Contracts/DTOInterface.php   | 69 +++++++++++++++++++++
 src/Core/DtoHydrator.php              | 89 +++++++++++++++++++++++++++
 src/Core/Traits/HydratesFromArray.php | 40 ++++++++++++
 src/Core/Traits/SerializesToArray.php | 71 +++++++++++++++++++++
 4 files changed, 269 insertions(+)
 create mode 100644 src/Core/Contracts/DTOInterface.php
 create mode 100644 src/Core/DtoHydrator.php
 create mode 100644 src/Core/Traits/HydratesFromArray.php
 create mode 100644 src/Core/Traits/SerializesToArray.php

diff --git a/src/Core/Contracts/DTOInterface.php b/src/Core/Contracts/DTOInterface.php
new file mode 100644
index 0000000..fed6fc6
--- /dev/null
+++ b/src/Core/Contracts/DTOInterface.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Core\Contracts;
+
+use JsonSerializable;
+
+/**
+ * Marks a class as an immutable API data-transfer object.
+ *
+ * DTOs carry structured data between the HTTP layer and the application.
+ * They are intentionally read-only: all properties are set during construction
+ * and must not be mutated afterwards. Implementing classes should use PHP 8.1+
+ * promoted readonly constructor parameters so that the constructor itself
+ * serves as the authoritative schema of the API resource.
+ *
+ * Hydration from raw API responses is provided via {@see self::fromArray()}.
+ * Serialization back to the wire format is provided via {@see self::toArray()}
+ * and {@see self::jsonSerialize()}.
+ *
+ * The {@see \ZammadAPIClient\Core\Traits\HydratesFromArray} and
+ * {@see \ZammadAPIClient\Core\Traits\SerializesToArray} traits supply
+ * default reflection-based implementations; override only when the API
+ * shape does not map 1:1 to the constructor parameter names.
+ */
+interface DTOInterface extends JsonSerializable
+{
+    /**
+     * Constructs a DTO from a raw API response array.
+     *
+     * Field names in $data are matched to constructor parameter names using
+     * reflection (via {@see \ZammadAPIClient\Core\DtoHydrator}). Unknown keys
+     * are silently ignored; missing keys resolve to the parameter's default
+     * value or null for nullable parameters.
+     *
+     * @param array<string, mixed> $data Raw JSON-decoded response from the API.
+     * @return static
+     */
+    public static function fromArray(array $data): static;
+
+    /**
+     * Serializes the DTO to an associative array suitable for API requests.
+     *
+     * Keys match the API field names. Null values are included so that
+     * callers can distinguish "not set" from "set to empty string".
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array;
+
+    /**
+     * Returns the server-assigned ID, or null before the object is persisted.
+     *
+     * The ID is assigned by Zammad on creation and is never set by the client.
+     * A null return value signals that the DTO represents an unsaved resource.
+     */
+    public function id(): ?int;
+
+    /**
+     * Alias of {@see self::toArray()} required by JsonSerializable.
+     *
+     * Enables direct JSON encoding: `json_encode($dto)` produces the same
+     * output as `json_encode($dto->toArray())`.
+     *
+     * @return array<string, mixed>
+     */
+    public function jsonSerialize(): array;
+}
diff --git a/src/Core/DtoHydrator.php b/src/Core/DtoHydrator.php
new file mode 100644
index 0000000..fd0c3f6
--- /dev/null
+++ b/src/Core/DtoHydrator.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Core;
+
+use DateTimeImmutable;
+use ReflectionClass;
+use ReflectionNamedType;
+
+/**
+ * Type-driven DTO hydration: maps array keys onto constructor parameters using
+ * each parameter's declared type. The constructor is the single source of
+ * truth; scalar coercion is delegated to {@see Cast}.
+ */
+final class DtoHydrator
+{
+    /**
+     * Cached constructor metadata per class: ordered list of name/type/nullable.
+     *
+     * @var array<class-string, list<array{name: string, type: ?string, nullable: bool}>>
+     */
+    private static array $metaCache = [];
+
+    /**
+     * Instantiates $class by mapping $data array keys to constructor parameters.
+     *
+     * The constructor is introspected once per class and the result is cached
+     * in {@see self::$metaCache} to avoid repeated reflection calls. Each
+     * parameter's declared type drives the coercion applied via {@see Cast}:
+     * e.g. a `?DateTimeImmutable` parameter gets `Cast::dateTime()`, a
+     * `string` parameter gets `Cast::string()`, etc. Parameters for which no
+     * key exists in $data receive null (nullable) or a zero-value (non-nullable).
+     *
+     * @template T of object
+     * @param class-string<T> $class Fully-qualified DTO class to instantiate.
+     * @param array<string, mixed> $data Raw API response fields.
+     * @return T
+     */
+    public static function hydrate(string $class, array $data): object
+    {
+        $args = [];
+
+        foreach (self::constructorMeta($class) as $param) {
+            $args[] = self::coerce($param['type'], $param['nullable'], $data, $param['name']);
+        }
+
+        return new $class(...$args);
+    }
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    private static function coerce(?string $type, bool $nullable, array $data, string $name): mixed
+    {
+        return match ($type) {
+            DateTimeImmutable::class => Cast::dateTime($data, $name),
+            'int' => $nullable ? Cast::intOrNull($data, $name) : (Cast::intOrNull($data, $name) ?? 0),
+            'bool' => $nullable ? Cast::boolOrNull($data, $name) : (Cast::boolOrNull($data, $name) ?? false),
+            'string' => $nullable ? Cast::stringOrNull($data, $name) : Cast::string($data, $name),
+            default => $data[$name] ?? null,
+        };
+    }
+
+    /**
+     * @param class-string $class
+     * @return list<array{name: string, type: ?string, nullable: bool}>
+     */
+    private static function constructorMeta(string $class): array
+    {
+        if (isset(self::$metaCache[$class])) {
+            return self::$metaCache[$class];
+        }
+
+        $constructor = (new ReflectionClass($class))->getConstructor();
+        $meta = [];
+
+        foreach ($constructor?->getParameters() ?? [] as $param) {
+            $type = $param->getType();
+            $meta[] = [
+                'name' => $param->getName(),
+                'type' => $type instanceof ReflectionNamedType ? $type->getName() : null,
+                'nullable' => $type === null || $type->allowsNull(),
+            ];
+        }
+
+        return self::$metaCache[$class] = $meta;
+    }
+}
diff --git a/src/Core/Traits/HydratesFromArray.php b/src/Core/Traits/HydratesFromArray.php
new file mode 100644
index 0000000..f394c3b
--- /dev/null
+++ b/src/Core/Traits/HydratesFromArray.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Core\Traits;
+
+use ZammadAPIClient\Core\DtoHydrator;
+
+/**
+ * Provides a reflection-based `fromArray()` implementation for DTOs.
+ *
+ * Delegates to {@see \ZammadAPIClient\Core\DtoHydrator::hydrate()}, which
+ * inspects the consuming class's constructor to determine parameter names and
+ * types, then maps matching keys from the raw API array using
+ * {@see \ZammadAPIClient\Core\Cast}. The constructor is the sole schema
+ * definition — no separate mapping configuration is needed.
+ *
+ * When the API field name differs from the constructor parameter, or when
+ * a fallback key must be tried (e.g. `owner_id` vs `owner`), override
+ * `fromArray()` in the specific DTO and call `parent::fromArray()` only
+ * after normalising the array. See {@see \ZammadAPIClient\Endpoints\Tickets\TicketDTO}
+ * for an example.
+ */
+trait HydratesFromArray
+{
+    /**
+     * Constructs a DTO from a raw API response array.
+     *
+     * Parameter names drive the field lookup: a constructor parameter named
+     * `$ticketId` will read $data['ticketId']. The hydration is case-sensitive
+     * and does not snake-case-convert parameter names.
+     *
+     * @param array<string, mixed> $data Raw JSON-decoded API response.
+     * @return static
+     */
+    public static function fromArray(array $data): static
+    {
+        return DtoHydrator::hydrate(static::class, $data);
+    }
+}
diff --git a/src/Core/Traits/SerializesToArray.php b/src/Core/Traits/SerializesToArray.php
new file mode 100644
index 0000000..23ea5e6
--- /dev/null
+++ b/src/Core/Traits/SerializesToArray.php
@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ZammadAPIClient\Core\Traits;
+
+use DateTimeImmutable;
+
+/**
+ * Provides standard DTO serialisation for classes with promoted readonly properties.
+ *
+ * Consuming DTOs must declare a public nullable `$id` property so that
+ * {@see self::id()} can return it. All other public properties are included
+ * in {@see self::toArray()} automatically via `get_object_vars()`.
+ *
+ * Serialisation rules:
+ *  - Null values are omitted so the API only receives explicitly set fields.
+ *  - DateTimeImmutable values are formatted as ISO 8601 strings (`c` format).
+ *  - All other scalar values are included as-is.
+ *
+ * Pair with {@see \ZammadAPIClient\Core\Traits\HydratesFromArray} for a
+ * complete, zero-boilerplate DTO implementation.
+ */
+trait SerializesToArray
+{
+    /**
+     * Serialises all non-null public properties to an associative array.
+     *
+     * The resulting array is suitable for API request bodies. DateTimeImmutable
+     * values are converted to ISO 8601 strings; all other values are passed
+     * through. Null properties are excluded so partial DTO construction does
+     * not send empty fields to the API.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        $result = [];
+        foreach (get_object_vars($this) as $key => $value) {
+            if ($value !== null) {
+                $result[$key] = $value instanceof DateTimeImmutable ? $value->format('c') : $value;
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * Returns the server-assigned resource ID, or null for unsaved DTOs.
+     *
+     * The consuming class must declare `public readonly ?int $id = null`.
+     * This method reads it directly; no property access indirection is used.
+     */
+    public function id(): ?int
+    {
+        return $this->id;
+    }
+
+    /**
+     * Delegates to {@see self::toArray()} to satisfy the JsonSerializable contract.
+     *
+     * Allows `json_encode($dto)` to produce the same output as
+     * `json_encode($dto->toArray())` without any extra code in the DTO.
+     *
+     * @return array<string, mixed>
+     */
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+}